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="pairIntegerInteger"> 62 <language name="java">android.util.Pair<Integer,Integer></language> 63 </typedef> 64 <typedef name="rectangle"> 65 <language name="java">android.graphics.Rect</language> 66 </typedef> 67 <typedef name="size"> 68 <language name="java">android.util.Size</language> 69 </typedef> 70 <typedef name="string"> 71 <language name="java">String</language> 72 </typedef> 73 <typedef name="boolean"> 74 <language name="java">boolean</language> 75 </typedef> 76 <typedef name="imageFormat"> 77 <language name="java">int</language> 78 </typedef> 79 <typedef name="versionCode"> 80 <language name="java">int</language> 81 </typedef> 82 <typedef name="streamConfigurationMap"> 83 <language name="java">android.hardware.camera2.params.StreamConfigurationMap</language> 84 </typedef> 85 <typedef name="streamConfiguration"> 86 <language name="java">android.hardware.camera2.params.StreamConfiguration</language> 87 </typedef> 88 <typedef name="recommendedStreamConfiguration"> 89 <language 90 name="java">android.hardware.camera2.params.RecommendedStreamConfiguration</language> 91 </typedef> 92 <typedef name="streamConfigurationDuration"> 93 <language name="java">android.hardware.camera2.params.StreamConfigurationDuration</language> 94 </typedef> 95 <typedef name="face"> 96 <language name="java">android.hardware.camera2.params.Face</language> 97 </typedef> 98 <typedef name="meteringRectangle"> 99 <language name="java">android.hardware.camera2.params.MeteringRectangle</language> 100 </typedef> 101 <typedef name="rangeFloat"> 102 <language name="java">android.util.Range<Float></language> 103 </typedef> 104 <typedef name="rangeInt"> 105 <language name="java">android.util.Range<Integer></language> 106 </typedef> 107 <typedef name="rangeLong"> 108 <language name="java">android.util.Range<Long></language> 109 </typedef> 110 <typedef name="colorSpaceTransform"> 111 <language name="java">android.hardware.camera2.params.ColorSpaceTransform</language> 112 </typedef> 113 <typedef name="rggbChannelVector"> 114 <language name="java">android.hardware.camera2.params.RggbChannelVector</language> 115 </typedef> 116 <typedef name="blackLevelPattern"> 117 <language name="java">android.hardware.camera2.params.BlackLevelPattern</language> 118 </typedef> 119 <typedef name="enumList"> 120 <language name="java">int</language> 121 </typedef> 122 <typedef name="sizeF"> 123 <language name="java">android.util.SizeF</language> 124 </typedef> 125 <typedef name="point"> 126 <language name="java">android.graphics.Point</language> 127 </typedef> 128 <typedef name="pointF"> 129 <language name="java">android.graphics.PointF</language> 130 </typedef> 131 <typedef name="tonemapCurve"> 132 <language name="java">android.hardware.camera2.params.TonemapCurve</language> 133 </typedef> 134 <typedef name="lensShadingMap"> 135 <language name="java">android.hardware.camera2.params.LensShadingMap</language> 136 </typedef> 137 <typedef name="location"> 138 <language name="java">android.location.Location</language> 139 </typedef> 140 <typedef name="highSpeedVideoConfiguration"> 141 <language name="java">android.hardware.camera2.params.HighSpeedVideoConfiguration</language> 142 </typedef> 143 <typedef name="reprocessFormatsMap"> 144 <language name="java">android.hardware.camera2.params.ReprocessFormatsMap</language> 145 </typedef> 146 <typedef name="oisSample"> 147 <language name="java">android.hardware.camera2.params.OisSample</language> 148 </typedef> 149 <typedef name="mandatoryStreamCombination"> 150 <language name="java">android.hardware.camera2.params.MandatoryStreamCombination</language> 151 </typedef> 152 <typedef name="capability"> 153 <language name="java">android.hardware.camera2.params.Capability</language> 154 </typedef> 155 <typedef name="multiResolutionStreamConfigurationMap"> 156 <language name="java">android.hardware.camera2.params.MultiResolutionStreamConfigurationMap</language> 157 </typedef> 158 <typedef name="deviceStateSensorOrientationMap"> 159 <language name="java">android.hardware.camera2.params.DeviceStateSensorOrientationMap</language> 160 </typedef> 161 <typedef name="dynamicRangeProfiles"> 162 <language name="java">android.hardware.camera2.params.DynamicRangeProfiles</language> 163 </typedef> 164 <typedef name="colorSpaceProfiles"> 165 <language name="java">android.hardware.camera2.params.ColorSpaceProfiles</language> 166 </typedef> 167 <typedef name="lensIntrinsicsSample"> 168 <language name="java">android.hardware.camera2.params.LensIntrinsicsSample</language> 169 </typedef> 170 <typedef name="sharedSessionConfiguration"> 171 <language name="java">android.hardware.camera2.params.SharedSessionConfiguration</language> 172 </typedef> 173 </types> 174 175 <namespace name="android"> 176 <section name="colorCorrection"> 177 <controls> 178 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 179 <enum> 180 <value>TRANSFORM_MATRIX 181 <notes>Use the android.colorCorrection.transform matrix 182 and android.colorCorrection.gains to do color conversion. 183 184 All advanced white balance adjustments (not specified 185 by our white balance pipeline) must be disabled. 186 187 If AWB is enabled with `android.control.awbMode != OFF`, then 188 TRANSFORM_MATRIX is ignored. The camera device will override 189 this value to either FAST or HIGH_QUALITY. 190 </notes> 191 </value> 192 <value>FAST 193 <notes>Color correction processing must not slow down 194 capture rate relative to sensor raw output. 195 196 Advanced white balance adjustments above and beyond 197 the specified white balance pipeline may be applied. 198 199 If AWB is enabled with `android.control.awbMode != OFF`, then 200 the camera device uses the last frame's AWB values 201 (or defaults if AWB has never been run). 202 </notes> 203 </value> 204 <value>HIGH_QUALITY 205 <notes>Color correction processing operates at improved 206 quality but the capture rate might be reduced (relative to sensor 207 raw output rate) 208 209 Advanced white balance adjustments above and beyond 210 the specified white balance pipeline may be applied. 211 212 If AWB is enabled with `android.control.awbMode != OFF`, then 213 the camera device uses the last frame's AWB values 214 (or defaults if AWB has never been run). 215 </notes> 216 </value> 217 <value hal_version="3.11" aconfig_flag="color_temperature">CCT 218 <notes>Use 219 android.colorCorrection.colorTemperature and 220 android.colorCorrection.colorTint to adjust the white balance based 221 on correlated color temperature. 222 223 If AWB is enabled with `android.control.awbMode != OFF`, then 224 CCT is ignored. 225 </notes> 226 </value> 227 </enum> 228 229 <description> 230 The mode control selects how the image data is converted from the 231 sensor's native color into linear sRGB color. 232 </description> 233 <range>Starting from API level 36, android.colorCorrection.availableModes 234 can be used to check the list of supported values. Prior to API level 36, 235 TRANSFORM_MATRIX, HIGH_QUALITY, and FAST are guaranteed to be available 236 as valid modes on devices that support this key.</range> 237 <details> 238 When auto-white balance (AWB) is enabled with android.control.awbMode, this 239 control is overridden by the AWB routine. When AWB is disabled, the 240 application controls how the color mapping is performed. 241 242 We define the expected processing pipeline below. For consistency 243 across devices, this is always the case with TRANSFORM_MATRIX. 244 245 When either FAST or HIGH_QUALITY is used, the camera device may 246 do additional processing but android.colorCorrection.gains and 247 android.colorCorrection.transform will still be provided by the 248 camera device (in the results) and be roughly correct. 249 250 Switching to TRANSFORM_MATRIX and using the data provided from 251 FAST or HIGH_QUALITY will yield a picture with the same white point 252 as what was produced by the camera device in the earlier frame. 253 254 The expected processing pipeline is as follows: 255 256  257 258 The white balance is encoded by two values, a 4-channel white-balance 259 gain vector (applied in the Bayer domain), and a 3x3 color transform 260 matrix (applied after demosaic). 261 262 The 4-channel white-balance gains are defined as: 263 264 android.colorCorrection.gains = [ R G_even G_odd B ] 265 266 where `G_even` is the gain for green pixels on even rows of the 267 output, and `G_odd` is the gain for green pixels on the odd rows. 268 These may be identical for a given camera device implementation; if 269 the camera device does not support a separate gain for even/odd green 270 channels, it will use the `G_even` value, and write `G_odd` equal to 271 `G_even` in the output result metadata. 272 273 The matrices for color transforms are defined as a 9-entry vector: 274 275 android.colorCorrection.transform = [ I0 I1 I2 I3 I4 I5 I6 I7 I8 ] 276 277 which define a transform from input sensor colors, `P_in = [ r g b ]`, 278 to output linear sRGB, `P_out = [ r' g' b' ]`, 279 280 with colors as follows: 281 282 r' = I0r + I1g + I2b 283 g' = I3r + I4g + I5b 284 b' = I6r + I7g + I8b 285 286 Both the input and output value ranges must match. Overflow/underflow 287 values are clipped to fit within the range. 288 </details> 289 <hal_details> 290 HAL must support both FAST and HIGH_QUALITY if color correction control is available 291 on the camera device, but the underlying implementation can be the same for both modes. 292 That is, if the highest quality implementation on the camera device does not slow down 293 capture rate, then FAST and HIGH_QUALITY should generate the same output. 294 </hal_details> 295 </entry> 296 <entry name="transform" type="rational" visibility="public" 297 type_notes="3x3 rational matrix in row-major order" 298 container="array" typedef="colorSpaceTransform" hwlevel="full"> 299 <array> 300 <size>3</size> 301 <size>3</size> 302 </array> 303 <description>A color transform matrix to use to transform 304 from sensor RGB color space to output linear sRGB color space. 305 </description> 306 <units>Unitless scale factors</units> 307 <details>This matrix is either set by the camera device when the request 308 android.colorCorrection.mode is not TRANSFORM_MATRIX, or 309 directly by the application in the request when the 310 android.colorCorrection.mode is TRANSFORM_MATRIX. 311 312 In the latter case, the camera device may round the matrix to account 313 for precision issues; the final rounded matrix should be reported back 314 in this matrix result metadata. The transform should keep the magnitude 315 of the output color values within `[0, 1.0]` (assuming input color 316 values is within the normalized range `[0, 1.0]`), or clipping may occur. 317 318 The valid range of each matrix element varies on different devices, but 319 values within [-1.5, 3.0] are guaranteed not to be clipped. 320 </details> 321 </entry> 322 <entry name="gains" type="float" visibility="public" 323 type_notes="A 1D array of floats for 4 color channel gains" 324 container="array" typedef="rggbChannelVector" hwlevel="full"> 325 <array> 326 <size>4</size> 327 </array> 328 <description>Gains applying to Bayer raw color channels for 329 white-balance.</description> 330 <units>Unitless gain factors</units> 331 <details> 332 These per-channel gains are either set by the camera device 333 when the request android.colorCorrection.mode is not 334 TRANSFORM_MATRIX, or directly by the application in the 335 request when the android.colorCorrection.mode is 336 TRANSFORM_MATRIX. 337 338 The gains in the result metadata are the gains actually 339 applied by the camera device to the current frame. 340 341 The valid range of gains varies on different devices, but gains 342 between [1.0, 3.0] are guaranteed not to be clipped. Even if a given 343 device allows gains below 1.0, this is usually not recommended because 344 this can create color artifacts. 345 </details> 346 <hal_details> 347 The 4-channel white-balance gains are defined in 348 the order of `[R G_even G_odd B]`, where `G_even` is the gain 349 for green pixels on even rows of the output, and `G_odd` 350 is the gain for green pixels on the odd rows. 351 352 If a HAL does not support a separate gain for even/odd green 353 channels, it must use the `G_even` value, and write 354 `G_odd` equal to `G_even` in the output result metadata. 355 </hal_details> 356 </entry> 357 <entry name="aberrationMode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 358 <enum> 359 <value>OFF 360 <notes> 361 No aberration correction is applied. 362 </notes> 363 </value> 364 <value>FAST 365 <notes> 366 Aberration correction will not slow down capture rate 367 relative to sensor raw output. 368 </notes> 369 </value> 370 <value>HIGH_QUALITY 371 <notes> 372 Aberration correction operates at improved quality but the capture rate might be 373 reduced (relative to sensor raw output rate) 374 </notes> 375 </value> 376 </enum> 377 <description> 378 Mode of operation for the chromatic aberration correction algorithm. 379 </description> 380 <range>android.colorCorrection.availableAberrationModes</range> 381 <details> 382 Chromatic (color) aberration is caused by the fact that different wavelengths of light 383 can not focus on the same point after exiting from the lens. This metadata defines 384 the high level control of chromatic aberration correction algorithm, which aims to 385 minimize the chromatic artifacts that may occur along the object boundaries in an 386 image. 387 388 FAST/HIGH_QUALITY both mean that camera device determined aberration 389 correction will be applied. HIGH_QUALITY mode indicates that the camera device will 390 use the highest-quality aberration correction algorithms, even if it slows down 391 capture rate. FAST means the camera device will not slow down capture rate when 392 applying aberration correction. 393 394 LEGACY devices will always be in FAST mode. 395 </details> 396 </entry> 397 </controls> 398 <dynamic> 399 <clone entry="android.colorCorrection.mode" kind="controls"> 400 </clone> 401 <clone entry="android.colorCorrection.transform" kind="controls"> 402 </clone> 403 <clone entry="android.colorCorrection.gains" kind="controls"> 404 </clone> 405 <clone entry="android.colorCorrection.aberrationMode" kind="controls"> 406 </clone> 407 </dynamic> 408 <static> 409 <entry name="availableAberrationModes" type="byte" visibility="public" 410 type_notes="list of enums" container="array" typedef="enumList" hwlevel="legacy"> 411 <array> 412 <size>n</size> 413 </array> 414 <description> 415 List of aberration correction modes for android.colorCorrection.aberrationMode that are 416 supported by this camera device. 417 </description> 418 <range>Any value listed in android.colorCorrection.aberrationMode</range> 419 <details> 420 This key lists the valid modes for android.colorCorrection.aberrationMode. If no 421 aberration correction modes are available for a device, this list will solely include 422 OFF mode. All camera devices will support either OFF or FAST mode. 423 424 Camera devices that support the MANUAL_POST_PROCESSING capability will always list 425 OFF mode. This includes all FULL level devices. 426 427 LEGACY devices will always only support FAST mode. 428 </details> 429 <hal_details> 430 HAL must support both FAST and HIGH_QUALITY if chromatic aberration control is available 431 on the camera device, but the underlying implementation can be the same for both modes. 432 That is, if the highest quality implementation on the camera device does not slow down 433 capture rate, then FAST and HIGH_QUALITY will generate the same output. 434 </hal_details> 435 <tag id="V1" /> 436 </entry> 437 </static> 438 <controls> 439 <entry name="colorTemperature" type="int32" visibility="public" optional="true" 440 aconfig_flag="color_temperature" hal_version="3.11"> 441 <description> 442 Specifies the color temperature for CCT mode in Kelvin 443 to adjust the white balance of the image. 444 </description> 445 <units>Kelvin</units> 446 <range>android.colorCorrection.colorTemperatureRange</range> 447 <details> 448 Sets the color temperature in Kelvin units for when 449 android.colorCorrection.mode is CCT to adjust the 450 white balance of the image. 451 452 If CCT mode is enabled without a requested color temperature, 453 a default value will be set by the camera device. The default value can be 454 retrieved by checking the corresponding capture result. Color temperatures 455 requested outside the advertised android.colorCorrection.colorTemperatureRange 456 will be clamped. 457 </details> 458 </entry> 459 <entry name="colorTint" type="int32" visibility="public" optional="true" 460 aconfig_flag="color_temperature" hal_version="3.11"> 461 <description> 462 Specifies the color tint for CCT mode to adjust the white 463 balance of the image. 464 </description> 465 <units>D_uv defined as the distance from the Planckian locus on the CIE 1931 xy 466 chromaticity diagram, with the range ±50 mapping to ±0.01 D_uv</units> 467 <range>The supported range, -50 to +50, corresponds to a D_uv distance 468 of ±0.01 below and above the Planckian locus. Some camera devices may have 469 limitations to achieving the full ±0.01 D_uv range at some color temperatures 470 (e.g., below 1500K). In these cases, the applied D_uv value may be clamped and 471 the actual color tint will be reported in the android.colorCorrection.colorTint 472 result.</range> 473 <details> 474 Sets the color tint for when android.colorCorrection.mode 475 is CCT to adjust the white balance of the image. 476 477 If CCT mode is enabled without a requested color tint, 478 a default value will be set by the camera device. The default value can be 479 retrieved by checking the corresponding capture result. Color tints requested 480 outside the supported range will be clamped to the nearest limit (-50 or +50). 481 </details> 482 </entry> 483 </controls> 484 <dynamic> 485 <clone entry="android.colorCorrection.colorTemperature" kind="controls"> 486 </clone> 487 <clone entry="android.colorCorrection.colorTint" kind="controls"> 488 </clone> 489 </dynamic> 490 <static> 491 <entry name="colorTemperatureRange" type="int32" visibility="public" 492 optional="true" container="array" typedef="rangeInt" 493 aconfig_flag="color_temperature" hal_version="3.11"> 494 <array> 495 <size>2</size> 496 </array> 497 <description>The range of supported color temperature values for 498 android.colorCorrection.colorTemperature.</description> 499 <range> 500 The minimum supported range will be [2856K,6500K]. The maximum supported 501 range will be [1000K,40000K]. 502 </range> 503 <details> 504 This key lists the valid range of color temperature values for 505 android.colorCorrection.colorTemperature supported by this camera device. 506 507 This key will be null on devices that do not support CCT mode for 508 android.colorCorrection.mode. 509 </details> 510 </entry> 511 <entry name="availableModes" type="byte" visibility="public" 512 optional="true" type_notes="list of enums" container="array" typedef="enumList" 513 aconfig_flag="color_temperature" hal_version="3.11"> 514 <array> 515 <size>n</size> 516 </array> 517 <description> 518 List of color correction modes for android.colorCorrection.mode that are 519 supported by this camera device. 520 </description> 521 <range>Any value listed in android.colorCorrection.mode</range> 522 <details> 523 This key lists the valid modes for android.colorCorrection.mode. If no 524 color correction modes are available for a device, this key will be null. 525 526 Camera devices that have a FULL hardware level will always include at least 527 FAST, HIGH_QUALITY, and TRANSFORM_MATRIX modes. 528 </details> 529 </entry> 530 </static> 531 </section> 532 <section name="control"> 533 <controls> 534 <entry name="aeAntibandingMode" type="byte" visibility="public" 535 enum="true" hwlevel="legacy"> 536 <enum> 537 <value>OFF 538 <notes> 539 The camera device will not adjust exposure duration to 540 avoid banding problems. 541 </notes> 542 </value> 543 <value>50HZ 544 <notes> 545 The camera device will adjust exposure duration to 546 avoid banding problems with 50Hz illumination sources. 547 </notes> 548 </value> 549 <value>60HZ 550 <notes> 551 The camera device will adjust exposure duration to 552 avoid banding problems with 60Hz illumination 553 sources. 554 </notes> 555 </value> 556 <value>AUTO 557 <notes> 558 The camera device will automatically adapt its 559 antibanding routine to the current illumination 560 condition. This is the default mode if AUTO is 561 available on given camera device. 562 </notes> 563 </value> 564 </enum> 565 <description> 566 The desired setting for the camera device's auto-exposure 567 algorithm's antibanding compensation. 568 </description> 569 <range> 570 android.control.aeAvailableAntibandingModes 571 </range> 572 <details> 573 Some kinds of lighting fixtures, such as some fluorescent 574 lights, flicker at the rate of the power supply frequency 575 (60Hz or 50Hz, depending on country). While this is 576 typically not noticeable to a person, it can be visible to 577 a camera device. If a camera sets its exposure time to the 578 wrong value, the flicker may become visible in the 579 viewfinder as flicker or in a final captured image, as a 580 set of variable-brightness bands across the image. 581 582 Therefore, the auto-exposure routines of camera devices 583 include antibanding routines that ensure that the chosen 584 exposure value will not cause such banding. The choice of 585 exposure time depends on the rate of flicker, which the 586 camera device can detect automatically, or the expected 587 rate can be selected by the application using this 588 control. 589 590 A given camera device may not support all of the possible 591 options for the antibanding mode. The 592 android.control.aeAvailableAntibandingModes key contains 593 the available modes for a given camera device. 594 595 AUTO mode is the default if it is available on given 596 camera device. When AUTO mode is not available, the 597 default will be either 50HZ or 60HZ, and both 50HZ 598 and 60HZ will be available. 599 600 If manual exposure control is enabled (by setting 601 android.control.aeMode or android.control.mode to OFF), 602 then this setting has no effect, and the application must 603 ensure it selects exposure times that do not cause banding 604 issues. The android.statistics.sceneFlicker key can assist 605 the application in this. 606 </details> 607 <hal_details> 608 For all capture request templates, this field must be set 609 to AUTO if AUTO mode is available. If AUTO is not available, 610 the default must be either 50HZ or 60HZ, and both 50HZ and 611 60HZ must be available. 612 613 If manual exposure control is enabled (by setting 614 android.control.aeMode or android.control.mode to OFF), 615 then the exposure values provided by the application must not be 616 adjusted for antibanding. 617 </hal_details> 618 <tag id="BC" /> 619 </entry> 620 <entry name="aeExposureCompensation" type="int32" visibility="public" hwlevel="legacy"> 621 <description>Adjustment to auto-exposure (AE) target image 622 brightness.</description> 623 <units>Compensation steps</units> 624 <range>android.control.aeCompensationRange</range> 625 <details> 626 The adjustment is measured as a count of steps, with the 627 step size defined by android.control.aeCompensationStep and the 628 allowed range by android.control.aeCompensationRange. 629 630 For example, if the exposure value (EV) step is 0.333, '6' 631 will mean an exposure compensation of +2 EV; -3 will mean an 632 exposure compensation of -1 EV. One EV represents a doubling 633 of image brightness. Note that this control will only be 634 effective if android.control.aeMode `!=` OFF. This control 635 will take effect even when android.control.aeLock `== true`. 636 637 In the event of exposure compensation value being changed, camera device 638 may take several frames to reach the newly requested exposure target. 639 During that time, android.control.aeState field will be in the SEARCHING 640 state. Once the new exposure target is reached, android.control.aeState will 641 change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or 642 FLASH_REQUIRED (if the scene is too dark for still capture). 643 </details> 644 <tag id="BC" /> 645 </entry> 646 <entry name="aeLock" type="byte" visibility="public" enum="true" 647 typedef="boolean" hwlevel="legacy"> 648 <enum> 649 <value>OFF 650 <notes>Auto-exposure lock is disabled; the AE algorithm 651 is free to update its parameters.</notes></value> 652 <value>ON 653 <notes>Auto-exposure lock is enabled; the AE algorithm 654 must not update the exposure and sensitivity parameters 655 while the lock is active. 656 657 android.control.aeExposureCompensation setting changes 658 will still take effect while auto-exposure is locked. 659 660 Some rare LEGACY devices may not support 661 this, in which case the value will always be overridden to OFF. 662 </notes></value> 663 </enum> 664 <description>Whether auto-exposure (AE) is currently locked to its latest 665 calculated values.</description> 666 <details> 667 When set to `true` (ON), the AE algorithm is locked to its latest parameters, 668 and will not change exposure settings until the lock is set to `false` (OFF). 669 670 Note that even when AE is locked, the flash may be fired if 671 the android.control.aeMode is ON_AUTO_FLASH / 672 ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE. 673 674 When android.control.aeExposureCompensation is changed, even if the AE lock 675 is ON, the camera device will still adjust its exposure value. 676 677 If AE precapture is triggered (see android.control.aePrecaptureTrigger) 678 when AE is already locked, the camera device will not change the exposure time 679 (android.sensor.exposureTime) and sensitivity (android.sensor.sensitivity) 680 parameters. The flash may be fired if the android.control.aeMode 681 is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the 682 android.control.aeMode is ON_ALWAYS_FLASH, the scene may become overexposed. 683 Similarly, AE precapture trigger CANCEL has no effect when AE is already locked. 684 685 When an AE precapture sequence is triggered, AE unlock will not be able to unlock 686 the AE if AE is locked by the camera device internally during precapture metering 687 sequence In other words, submitting requests with AE unlock has no effect for an 688 ongoing precapture metering sequence. Otherwise, the precapture metering sequence 689 will never succeed in a sequence of preview requests where AE lock is always set 690 to `false`. 691 692 Since the camera device has a pipeline of in-flight requests, the settings that 693 get locked do not necessarily correspond to the settings that were present in the 694 latest capture result received from the camera device, since additional captures 695 and AE updates may have occurred even before the result was sent out. If an 696 application is switching between automatic and manual control and wishes to eliminate 697 any flicker during the switch, the following procedure is recommended: 698 699 1. Starting in auto-AE mode: 700 2. Lock AE 701 3. Wait for the first result to be output that has the AE locked 702 4. Copy exposure settings from that result into a request, set the request to manual AE 703 5. Submit the capture request, proceed to run manual AE as desired. 704 705 See android.control.aeState for AE lock related state transition details. 706 </details> 707 <tag id="BC" /> 708 </entry> 709 <entry name="aeMode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 710 <enum> 711 <value>OFF 712 <notes> 713 The camera device's autoexposure routine is disabled. 714 715 The application-selected android.sensor.exposureTime, 716 android.sensor.sensitivity and 717 android.sensor.frameDuration are used by the camera 718 device, along with android.flash.* fields, if there's 719 a flash unit for this camera device. 720 721 Note that auto-white balance (AWB) and auto-focus (AF) 722 behavior is device dependent when AE is in OFF mode. 723 To have consistent behavior across different devices, 724 it is recommended to either set AWB and AF to OFF mode 725 or lock AWB and AF before setting AE to OFF. 726 See android.control.awbMode, android.control.afMode, 727 android.control.awbLock, and android.control.afTrigger 728 for more details. 729 730 LEGACY devices do not support the OFF mode and will 731 override attempts to use this value to ON. 732 </notes> 733 </value> 734 <value>ON 735 <notes> 736 The camera device's autoexposure routine is active, 737 with no flash control. 738 739 The application's values for 740 android.sensor.exposureTime, 741 android.sensor.sensitivity, and 742 android.sensor.frameDuration are ignored. The 743 application has control over the various 744 android.flash.* fields. 745 746 If the device supports manual flash strength control, i.e., 747 if android.flash.singleStrengthMaxLevel and 748 android.flash.torchStrengthMaxLevel are greater than 1, then 749 the auto-exposure (AE) precapture metering sequence should be 750 triggered for the configured flash mode and strength to avoid 751 the image being incorrectly exposed at different 752 android.flash.strengthLevel. 753 </notes> 754 </value> 755 <value>ON_AUTO_FLASH 756 <notes> 757 Like ON, except that the camera device also controls 758 the camera's flash unit, firing it in low-light 759 conditions. 760 761 The flash may be fired during a precapture sequence 762 (triggered by android.control.aePrecaptureTrigger) and 763 may be fired for captures for which the 764 android.control.captureIntent field is set to 765 STILL_CAPTURE 766 </notes> 767 </value> 768 <value>ON_ALWAYS_FLASH 769 <notes> 770 Like ON, except that the camera device also controls 771 the camera's flash unit, always firing it for still 772 captures. 773 774 The flash may be fired during a precapture sequence 775 (triggered by android.control.aePrecaptureTrigger) and 776 will always be fired for captures for which the 777 android.control.captureIntent field is set to 778 STILL_CAPTURE 779 </notes> 780 </value> 781 <value>ON_AUTO_FLASH_REDEYE 782 <notes> 783 Like ON_AUTO_FLASH, but with automatic red eye 784 reduction. 785 786 If deemed necessary by the camera device, a red eye 787 reduction flash will fire during the precapture 788 sequence. 789 </notes> 790 </value> 791 <value hal_version="3.3">ON_EXTERNAL_FLASH 792 <notes> 793 An external flash has been turned on. 794 795 It informs the camera device that an external flash has been turned on, and that 796 metering (and continuous focus if active) should be quickly recalculated to account 797 for the external flash. Otherwise, this mode acts like ON. 798 799 When the external flash is turned off, AE mode should be changed to one of the 800 other available AE modes. 801 802 If the camera device supports AE external flash mode, android.control.aeState must 803 be FLASH_REQUIRED after the camera device finishes AE scan and it's too dark without 804 flash. 805 </notes> 806 </value> 807 <value optional="true" hal_version="3.10" 808 aconfig_flag="camera_ae_mode_low_light_boost">ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY 809 <notes> 810 Like 'ON' but applies additional brightness boost in low light scenes. 811 812 When the scene lighting conditions are within the range defined by 813 android.control.lowLightBoostInfoLuminanceRange this mode will apply additional 814 brightness boost. 815 816 This mode will automatically adjust the intensity of low light boost applied 817 according to the scene lighting conditions. A darker scene will receive more boost 818 while a brighter scene will receive less boost. 819 820 This mode can ignore the set target frame rate to allow more light to be captured 821 which can result in choppier motion. The frame rate can extend to lower than the 822 android.control.aeAvailableTargetFpsRanges but will not go below 10 FPS. This mode 823 can also increase the sensor sensitivity gain which can result in increased luma 824 and chroma noise. The sensor sensitivity gain can extend to higher values beyond 825 android.sensor.info.sensitivityRange. This mode may also apply additional 826 processing to recover details in dark and bright areas of the image,and noise 827 reduction at high sensitivity gain settings to manage the trade-off between light 828 sensitivity and capture noise. 829 830 This mode is restricted to two output surfaces. One output surface type can either 831 be SurfaceView or TextureView. Another output surface type can either be MediaCodec 832 or MediaRecorder. This mode cannot be used with a target FPS range higher than 30 833 FPS. 834 835 If the session configuration is not supported, the AE mode reported in the 836 CaptureResult will be 'ON' instead of 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY'. 837 838 When this AE mode is enabled, the CaptureResult field 839 android.control.lowLightBoostState will indicate when low light boost is 'ACTIVE' 840 or 'INACTIVE'. By default android.control.lowLightBoostState will be 'INACTIVE'. 841 842 The low light boost is 'ACTIVE' once the scene lighting condition is less than the 843 upper bound lux value defined by android.control.lowLightBoostInfoLuminanceRange. 844 This mode will be 'INACTIVE' once the scene lighting condition is greater than the 845 upper bound lux value defined by android.control.lowLightBoostInfoLuminanceRange. 846 </notes> 847 </value> 848 </enum> 849 <description>The desired mode for the camera device's 850 auto-exposure routine.</description> 851 <range>android.control.aeAvailableModes</range> 852 <details> 853 This control is only effective if android.control.mode is 854 AUTO. 855 856 When set to any of the ON modes, the camera device's 857 auto-exposure routine is enabled, overriding the 858 application's selected exposure time, sensor sensitivity, 859 and frame duration (android.sensor.exposureTime, 860 android.sensor.sensitivity, and 861 android.sensor.frameDuration). If android.control.aePriorityMode is 862 enabled, the relevant priority CaptureRequest settings will not be overridden. 863 See android.control.aePriorityMode for more details. If one of the FLASH modes 864 is selected, the camera device's flash unit controls are 865 also overridden. 866 867 The FLASH modes are only available if the camera device 868 has a flash unit (android.flash.info.available is `true`). 869 870 If flash TORCH mode is desired, this field must be set to 871 ON or OFF, and android.flash.mode set to TORCH. 872 873 When set to any of the ON modes, the values chosen by the 874 camera device auto-exposure routine for the overridden 875 fields for a given capture will be available in its 876 CaptureResult. 877 878 When android.control.aeMode is AE_MODE_ON and if the device 879 supports manual flash strength control, i.e., 880 if android.flash.singleStrengthMaxLevel and 881 android.flash.torchStrengthMaxLevel are greater than 1, then 882 the auto-exposure (AE) precapture metering sequence should be 883 triggered to avoid the image being incorrectly exposed at 884 different android.flash.strengthLevel. 885 </details> 886 <tag id="BC" /> 887 </entry> 888 <entry name="aeRegions" type="int32" visibility="public" 889 optional="true" container="array" typedef="meteringRectangle"> 890 <array> 891 <size>5</size> 892 <size>area_count</size> 893 </array> 894 <description>List of metering areas to use for auto-exposure adjustment.</description> 895 <units>Pixel coordinates within android.sensor.info.activeArraySize or 896 android.sensor.info.preCorrectionActiveArraySize depending on 897 distortion correction capability and mode</units> 898 <range>Coordinates must be between `[(0,0), (width, height))` of 899 android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize 900 depending on distortion correction capability and mode</range> 901 <details> 902 Not available if android.control.maxRegionsAe is 0. 903 Otherwise will always be present. 904 905 The maximum number of regions supported by the device is determined by the value 906 of android.control.maxRegionsAe. 907 908 For devices not supporting android.distortionCorrection.mode control, the coordinate 909 system always follows that of android.sensor.info.activeArraySize, with (0,0) being 910 the top-left pixel in the active pixel array, and 911 (android.sensor.info.activeArraySize.width - 1, 912 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 913 active pixel array. 914 915 For devices supporting android.distortionCorrection.mode control, the coordinate 916 system depends on the mode being set. 917 When the distortion correction mode is OFF, the coordinate system follows 918 android.sensor.info.preCorrectionActiveArraySize, with 919 `(0, 0)` being the top-left pixel of the pre-correction active array, and 920 (android.sensor.info.preCorrectionActiveArraySize.width - 1, 921 android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right 922 pixel in the pre-correction active pixel array. 923 When the distortion correction mode is not OFF, the coordinate system follows 924 android.sensor.info.activeArraySize, with 925 `(0, 0)` being the top-left pixel of the active array, and 926 (android.sensor.info.activeArraySize.width - 1, 927 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 928 active pixel array. 929 930 The weight must be within `[0, 1000]`, and represents a weight 931 for every pixel in the area. This means that a large metering area 932 with the same weight as a smaller area will have more effect in 933 the metering result. Metering areas can partially overlap and the 934 camera device will add the weights in the overlap region. 935 936 The weights are relative to weights of other exposure metering regions, so if only one 937 region is used, all non-zero weights will have the same effect. A region with 0 938 weight is ignored. 939 940 If all regions have 0 weight, then no specific metering area needs to be used by the 941 camera device. 942 943 If the metering region is outside the used android.scaler.cropRegion returned in 944 capture result metadata, the camera device will ignore the sections outside the crop 945 region and output only the intersection rectangle as the metering region in the result 946 metadata. If the region is entirely outside the crop region, it will be ignored and 947 not reported in the result metadata. 948 949 When setting the AE metering regions, the application must consider the additional 950 crop resulted from the aspect ratio differences between the preview stream and 951 android.scaler.cropRegion. For example, if the android.scaler.cropRegion is the full 952 active array size with 4:3 aspect ratio, and the preview stream is 16:9, 953 the boundary of AE regions will be [0, y_crop] and 954 [active_width, active_height - 2 * y_crop] rather than [0, 0] and 955 [active_width, active_height], where y_crop is the additional crop due to aspect ratio 956 mismatch. 957 958 Starting from API level 30, the coordinate system of activeArraySize or 959 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 960 pre-zoom field of view. This means that the same aeRegions values at different 961 android.control.zoomRatio represent different parts of the scene. The aeRegions 962 coordinates are relative to the activeArray/preCorrectionActiveArray representing the 963 zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same 964 aeRegions at different android.scaler.cropRegion still represent the same parts of the 965 scene as they do before. See android.control.zoomRatio for details. Whether to use 966 activeArraySize or preCorrectionActiveArraySize still depends on distortion correction 967 mode. 968 969 For camera devices with the 970 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 971 capability or devices where 972 {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 973 lists android.sensor.pixelMode, 974 android.sensor.info.activeArraySizeMaximumResolution / 975 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 976 coordinate system for requests where android.sensor.pixelMode is set to 977 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 978 </details> 979 <ndk_details> 980 The data representation is `int[5 * area_count]`. 981 Every five elements represent a metering region of `(xmin, ymin, xmax, ymax, weight)`. 982 The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and 983 ymax. 984 </ndk_details> 985 <hal_details> 986 The HAL level representation of MeteringRectangle[] is a 987 int[5 * area_count]. 988 Every five elements represent a metering region of 989 (xmin, ymin, xmax, ymax, weight). 990 The rectangle is defined to be inclusive on xmin and ymin, but 991 exclusive on xmax and ymax. 992 HAL must always report metering regions in the coordinate system of pre-correction 993 active array. 994 </hal_details> 995 <tag id="BC" /> 996 </entry> 997 <entry name="aeTargetFpsRange" type="int32" visibility="public" 998 container="array" typedef="rangeInt" hwlevel="legacy"> 999 <array> 1000 <size>2</size> 1001 </array> 1002 <description>Range over which the auto-exposure routine can 1003 adjust the capture frame rate to maintain good 1004 exposure.</description> 1005 <units>Frames per second (FPS)</units> 1006 <range>Any of the entries in android.control.aeAvailableTargetFpsRanges</range> 1007 <details>Only constrains auto-exposure (AE) algorithm, not 1008 manual control of android.sensor.exposureTime and 1009 android.sensor.frameDuration. 1010 1011 Note that the actual achievable max framerate also depends on the minimum frame 1012 duration of the output streams. The max frame rate will be 1013 `min(aeTargetFpsRange.maxFps, 1 / max(individual stream min durations))`. For example, 1014 if the application sets this key to `{60, 60}`, but the maximum minFrameDuration among 1015 all configured streams is 33ms, the maximum framerate won't be 60fps, but will be 1016 30fps. 1017 1018 To start a CaptureSession with a target FPS range different from the 1019 capture request template's default value, the application 1020 is strongly recommended to call 1021 {@link android.hardware.camera2.params.SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters} 1022 with the target fps range before creating the capture session. The aeTargetFpsRange is 1023 typically a session parameter. Specifying it at session creation time helps avoid 1024 session reconfiguration delays in cases like 60fps or high speed recording. 1025 </details> 1026 <tag id="BC" /> 1027 </entry> 1028 <entry name="aePrecaptureTrigger" type="byte" visibility="public" 1029 enum="true" hwlevel="limited"> 1030 <enum> 1031 <value>IDLE 1032 <notes>The trigger is idle.</notes> 1033 </value> 1034 <value>START 1035 <notes>The precapture metering sequence will be started 1036 by the camera device. 1037 1038 The exact effect of the precapture trigger depends on 1039 the current AE mode and state.</notes> 1040 </value> 1041 <value>CANCEL 1042 <notes>The camera device will cancel any currently active or completed 1043 precapture metering sequence, the auto-exposure routine will return to its 1044 initial state.</notes> 1045 </value> 1046 </enum> 1047 <description>Whether the camera device will trigger a precapture 1048 metering sequence when it processes this request.</description> 1049 <details>This entry is normally set to IDLE, or is not 1050 included at all in the request settings. When included and 1051 set to START, the camera device will trigger the auto-exposure (AE) 1052 precapture metering sequence. 1053 1054 When set to CANCEL, the camera device will cancel any active 1055 precapture metering trigger, and return to its initial AE state. 1056 If a precapture metering sequence is already completed, and the camera 1057 device has implicitly locked the AE for subsequent still capture, the 1058 CANCEL trigger will unlock the AE and return to its initial AE state. 1059 1060 The precapture sequence should be triggered before starting a 1061 high-quality still capture for final metering decisions to 1062 be made, and for firing pre-capture flash pulses to estimate 1063 scene brightness and required final capture flash power, when 1064 the flash is enabled. 1065 1066 Flash is enabled during precapture sequence when: 1067 1068 * AE mode is ON_ALWAYS_FLASH 1069 * AE mode is ON_AUTO_FLASH and the scene is deemed too dark without flash, or 1070 * AE mode is ON and flash mode is TORCH or SINGLE 1071 1072 Normally, this entry should be set to START for only single request, and the 1073 application should wait until the sequence completes before starting a new one. 1074 1075 When a precapture metering sequence is finished, the camera device 1076 may lock the auto-exposure routine internally to be able to accurately expose the 1077 subsequent still capture image (`android.control.captureIntent == STILL_CAPTURE`). 1078 For this case, the AE may not resume normal scan if no subsequent still capture is 1079 submitted. To ensure that the AE routine restarts normal scan, the application should 1080 submit a request with `android.control.aeLock == true`, followed by a request 1081 with `android.control.aeLock == false`, if the application decides not to submit a 1082 still capture request after the precapture sequence completes. Alternatively, for 1083 API level 23 or newer devices, the CANCEL can be used to unlock the camera device 1084 internally locked AE if the application doesn't submit a still capture request after 1085 the AE precapture trigger. Note that, the CANCEL was added in API level 23, and must not 1086 be used in devices that have earlier API levels. 1087 1088 The exact effect of auto-exposure (AE) precapture trigger 1089 depends on the current AE mode and state; see 1090 android.control.aeState for AE precapture state transition 1091 details. 1092 1093 On LEGACY-level devices, the precapture trigger is not supported; 1094 capturing a high-resolution JPEG image will automatically trigger a 1095 precapture sequence before the high-resolution capture, including 1096 potentially firing a pre-capture flash. 1097 1098 Using the precapture trigger and the auto-focus trigger android.control.afTrigger 1099 simultaneously is allowed. However, since these triggers often require cooperation between 1100 the auto-focus and auto-exposure routines (for example, the may need to be enabled for a 1101 focus sweep), the camera device may delay acting on a later trigger until the previous 1102 trigger has been fully handled. This may lead to longer intervals between the trigger and 1103 changes to android.control.aeState indicating the start of the precapture sequence, for 1104 example. 1105 1106 If both the precapture and the auto-focus trigger are activated on the same request, then 1107 the camera device will complete them in the optimal order for that device. 1108 </details> 1109 <hal_details> 1110 The HAL must support triggering the AE precapture trigger while an AF trigger is active 1111 (and vice versa), or at the same time as the AF trigger. It is acceptable for the HAL to 1112 treat these as two consecutive triggers, for example handling the AF trigger and then the 1113 AE trigger. Or the HAL may choose to optimize the case with both triggers fired at once, 1114 to minimize the latency for converging both focus and exposure/flash usage. 1115 </hal_details> 1116 <tag id="BC" /> 1117 </entry> 1118 <entry name="afMode" type="byte" visibility="public" enum="true" 1119 hwlevel="legacy"> 1120 <enum> 1121 <value>OFF 1122 <notes>The auto-focus routine does not control the lens; 1123 android.lens.focusDistance is controlled by the 1124 application.</notes></value> 1125 <value>AUTO 1126 <notes>Basic automatic focus mode. 1127 1128 In this mode, the lens does not move unless 1129 the autofocus trigger action is called. When that trigger 1130 is activated, AF will transition to ACTIVE_SCAN, then to 1131 the outcome of the scan (FOCUSED or NOT_FOCUSED). 1132 1133 Always supported if lens is not fixed focus. 1134 1135 Use android.lens.info.minimumFocusDistance to determine if lens 1136 is fixed-focus. 1137 1138 Triggering AF_CANCEL resets the lens position to default, 1139 and sets the AF state to INACTIVE.</notes></value> 1140 <value>MACRO 1141 <notes>Close-up focusing mode. 1142 1143 In this mode, the lens does not move unless the 1144 autofocus trigger action is called. When that trigger is 1145 activated, AF will transition to ACTIVE_SCAN, then to 1146 the outcome of the scan (FOCUSED or NOT_FOCUSED). This 1147 mode is optimized for focusing on objects very close to 1148 the camera. 1149 1150 When that trigger is activated, AF will transition to 1151 ACTIVE_SCAN, then to the outcome of the scan (FOCUSED or 1152 NOT_FOCUSED). Triggering cancel AF resets the lens 1153 position to default, and sets the AF state to 1154 INACTIVE.</notes></value> 1155 <value>CONTINUOUS_VIDEO 1156 <notes>In this mode, the AF algorithm modifies the lens 1157 position continually to attempt to provide a 1158 constantly-in-focus image stream. 1159 1160 The focusing behavior should be suitable for good quality 1161 video recording; typically this means slower focus 1162 movement and no overshoots. When the AF trigger is not 1163 involved, the AF algorithm should start in INACTIVE state, 1164 and then transition into PASSIVE_SCAN and PASSIVE_FOCUSED 1165 states as appropriate. When the AF trigger is activated, 1166 the algorithm should immediately transition into 1167 AF_FOCUSED or AF_NOT_FOCUSED as appropriate, and lock the 1168 lens position until a cancel AF trigger is received. 1169 1170 Once cancel is received, the algorithm should transition 1171 back to INACTIVE and resume passive scan. Note that this 1172 behavior is not identical to CONTINUOUS_PICTURE, since an 1173 ongoing PASSIVE_SCAN must immediately be 1174 canceled.</notes></value> 1175 <value>CONTINUOUS_PICTURE 1176 <notes>In this mode, the AF algorithm modifies the lens 1177 position continually to attempt to provide a 1178 constantly-in-focus image stream. 1179 1180 The focusing behavior should be suitable for still image 1181 capture; typically this means focusing as fast as 1182 possible. When the AF trigger is not involved, the AF 1183 algorithm should start in INACTIVE state, and then 1184 transition into PASSIVE_SCAN and PASSIVE_FOCUSED states as 1185 appropriate as it attempts to maintain focus. When the AF 1186 trigger is activated, the algorithm should finish its 1187 PASSIVE_SCAN if active, and then transition into 1188 AF_FOCUSED or AF_NOT_FOCUSED as appropriate, and lock the 1189 lens position until a cancel AF trigger is received. 1190 1191 When the AF cancel trigger is activated, the algorithm 1192 should transition back to INACTIVE and then act as if it 1193 has just been started.</notes></value> 1194 <value>EDOF 1195 <notes>Extended depth of field (digital focus) mode. 1196 1197 The camera device will produce images with an extended 1198 depth of field automatically; no special focusing 1199 operations need to be done before taking a picture. 1200 1201 AF triggers are ignored, and the AF state will always be 1202 INACTIVE.</notes></value> 1203 </enum> 1204 <description>Whether auto-focus (AF) is currently enabled, and what 1205 mode it is set to.</description> 1206 <range>android.control.afAvailableModes</range> 1207 <details>Only effective if android.control.mode = AUTO and the lens is not fixed focus 1208 (i.e. `android.lens.info.minimumFocusDistance > 0`). Also note that 1209 when android.control.aeMode is OFF, the behavior of AF is device 1210 dependent. It is recommended to lock AF by using android.control.afTrigger before 1211 setting android.control.aeMode to OFF, or set AF mode to OFF when AE is OFF. 1212 1213 If the lens is controlled by the camera device auto-focus algorithm, 1214 the camera device will report the current AF status in android.control.afState 1215 in result metadata.</details> 1216 <hal_details> 1217 When afMode is AUTO or MACRO, the lens must not move until an AF trigger is sent in a 1218 request (android.control.afTrigger `==` START). After an AF trigger, the afState will end 1219 up with either FOCUSED_LOCKED or NOT_FOCUSED_LOCKED state (see 1220 android.control.afState for detailed state transitions), which indicates that the lens is 1221 locked and will not move. If camera movement (e.g. tilting camera) causes the lens to move 1222 after the lens is locked, the HAL must compensate this movement appropriately such that 1223 the same focal plane remains in focus. 1224 1225 When afMode is one of the continuous auto focus modes, the HAL is free to start a AF 1226 scan whenever it's not locked. When the lens is locked after an AF trigger 1227 (see android.control.afState for detailed state transitions), the HAL should maintain the 1228 same lock behavior as above. 1229 1230 When afMode is OFF, the application controls focus manually. The accuracy of the 1231 focus distance control depends on the android.lens.info.focusDistanceCalibration. 1232 However, the lens must not move regardless of the camera movement for any focus distance 1233 manual control. 1234 1235 To put this in concrete terms, if the camera has lens elements which may move based on 1236 camera orientation or motion (e.g. due to gravity), then the HAL must drive the lens to 1237 remain in a fixed position invariant to the camera's orientation or motion, for example, 1238 by using accelerometer measurements in the lens control logic. This is a typical issue 1239 that will arise on camera modules with open-loop VCMs. 1240 </hal_details> 1241 <tag id="BC" /> 1242 </entry> 1243 <entry name="afRegions" type="int32" visibility="public" 1244 optional="true" container="array" typedef="meteringRectangle"> 1245 <array> 1246 <size>5</size> 1247 <size>area_count</size> 1248 </array> 1249 <description>List of metering areas to use for auto-focus.</description> 1250 <units>Pixel coordinates within android.sensor.info.activeArraySize or 1251 android.sensor.info.preCorrectionActiveArraySize depending on 1252 distortion correction capability and mode</units> 1253 <range>Coordinates must be between `[(0,0), (width, height))` of 1254 android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize 1255 depending on distortion correction capability and mode</range> 1256 <details> 1257 Not available if android.control.maxRegionsAf is 0. 1258 Otherwise will always be present. 1259 1260 The maximum number of focus areas supported by the device is determined by the value 1261 of android.control.maxRegionsAf. 1262 1263 1264 For devices not supporting android.distortionCorrection.mode control, the coordinate 1265 system always follows that of android.sensor.info.activeArraySize, with (0,0) being 1266 the top-left pixel in the active pixel array, and 1267 (android.sensor.info.activeArraySize.width - 1, 1268 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1269 active pixel array. 1270 1271 For devices supporting android.distortionCorrection.mode control, the coordinate 1272 system depends on the mode being set. 1273 When the distortion correction mode is OFF, the coordinate system follows 1274 android.sensor.info.preCorrectionActiveArraySize, with 1275 `(0, 0)` being the top-left pixel of the pre-correction active array, and 1276 (android.sensor.info.preCorrectionActiveArraySize.width - 1, 1277 android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right 1278 pixel in the pre-correction active pixel array. 1279 When the distortion correction mode is not OFF, the coordinate system follows 1280 android.sensor.info.activeArraySize, with 1281 `(0, 0)` being the top-left pixel of the active array, and 1282 (android.sensor.info.activeArraySize.width - 1, 1283 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1284 active pixel array. 1285 1286 The weight must be within `[0, 1000]`, and represents a weight 1287 for every pixel in the area. This means that a large metering area 1288 with the same weight as a smaller area will have more effect in 1289 the metering result. Metering areas can partially overlap and the 1290 camera device will add the weights in the overlap region. 1291 1292 The weights are relative to weights of other metering regions, so if only one region 1293 is used, all non-zero weights will have the same effect. A region with 0 weight is 1294 ignored. 1295 1296 If all regions have 0 weight, then no specific metering area needs to be used by the 1297 camera device. The capture result will either be a zero weight region as well, or 1298 the region selected by the camera device as the focus area of interest. 1299 1300 If the metering region is outside the used android.scaler.cropRegion returned in 1301 capture result metadata, the camera device will ignore the sections outside the crop 1302 region and output only the intersection rectangle as the metering region in the result 1303 metadata. If the region is entirely outside the crop region, it will be ignored and 1304 not reported in the result metadata. 1305 1306 When setting the AF metering regions, the application must consider the additional 1307 crop resulted from the aspect ratio differences between the preview stream and 1308 android.scaler.cropRegion. For example, if the android.scaler.cropRegion is the full 1309 active array size with 4:3 aspect ratio, and the preview stream is 16:9, 1310 the boundary of AF regions will be [0, y_crop] and 1311 [active_width, active_height - 2 * y_crop] rather than [0, 0] and 1312 [active_width, active_height], where y_crop is the additional crop due to aspect ratio 1313 mismatch. 1314 1315 Starting from API level 30, the coordinate system of activeArraySize or 1316 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 1317 pre-zoom field of view. This means that the same afRegions values at different 1318 android.control.zoomRatio represent different parts of the scene. The afRegions 1319 coordinates are relative to the activeArray/preCorrectionActiveArray representing the 1320 zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same 1321 afRegions at different android.scaler.cropRegion still represent the same parts of the 1322 scene as they do before. See android.control.zoomRatio for details. Whether to use 1323 activeArraySize or preCorrectionActiveArraySize still depends on distortion correction 1324 mode. 1325 1326 For camera devices with the 1327 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 1328 capability or devices where 1329 {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 1330 lists android.sensor.pixelMode, 1331 android.sensor.info.activeArraySizeMaximumResolution / 1332 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 1333 coordinate system for requests where android.sensor.pixelMode is set to 1334 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 1335 </details> 1336 <ndk_details> 1337 The data representation is `int[5 * area_count]`. 1338 Every five elements represent a metering region of `(xmin, ymin, xmax, ymax, weight)`. 1339 The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and 1340 ymax. 1341 </ndk_details> 1342 <hal_details> 1343 The HAL level representation of MeteringRectangle[] is a 1344 int[5 * area_count]. 1345 Every five elements represent a metering region of 1346 (xmin, ymin, xmax, ymax, weight). 1347 The rectangle is defined to be inclusive on xmin and ymin, but 1348 exclusive on xmax and ymax. 1349 HAL must always report metering regions in the coordinate system of pre-correction 1350 active array. 1351 </hal_details> 1352 <tag id="BC" /> 1353 </entry> 1354 <entry name="afTrigger" type="byte" visibility="public" enum="true" 1355 hwlevel="legacy"> 1356 <enum> 1357 <value>IDLE 1358 <notes>The trigger is idle.</notes> 1359 </value> 1360 <value>START 1361 <notes>Autofocus will trigger now.</notes> 1362 </value> 1363 <value>CANCEL 1364 <notes>Autofocus will return to its initial 1365 state, and cancel any currently active trigger.</notes> 1366 </value> 1367 </enum> 1368 <description> 1369 Whether the camera device will trigger autofocus for this request. 1370 </description> 1371 <details>This entry is normally set to IDLE, or is not 1372 included at all in the request settings. 1373 1374 When included and set to START, the camera device will trigger the 1375 autofocus algorithm. If autofocus is disabled, this trigger has no effect. 1376 1377 When set to CANCEL, the camera device will cancel any active trigger, 1378 and return to its initial AF state. 1379 1380 Generally, applications should set this entry to START or CANCEL for only a 1381 single capture, and then return it to IDLE (or not set at all). Specifying 1382 START for multiple captures in a row means restarting the AF operation over 1383 and over again. 1384 1385 See android.control.afState for what the trigger means for each AF mode. 1386 1387 Using the autofocus trigger and the precapture trigger android.control.aePrecaptureTrigger 1388 simultaneously is allowed. However, since these triggers often require cooperation between 1389 the auto-focus and auto-exposure routines (for example, the may need to be enabled for a 1390 focus sweep), the camera device may delay acting on a later trigger until the previous 1391 trigger has been fully handled. This may lead to longer intervals between the trigger and 1392 changes to android.control.afState, for example. 1393 </details> 1394 <hal_details> 1395 The HAL must support triggering the AF trigger while an AE precapture trigger is active 1396 (and vice versa), or at the same time as the AE trigger. It is acceptable for the HAL to 1397 treat these as two consecutive triggers, for example handling the AF trigger and then the 1398 AE trigger. Or the HAL may choose to optimize the case with both triggers fired at once, 1399 to minimize the latency for converging both focus and exposure/flash usage. 1400 </hal_details> 1401 <tag id="BC" /> 1402 </entry> 1403 <entry name="awbLock" type="byte" visibility="public" enum="true" 1404 typedef="boolean" hwlevel="legacy"> 1405 <enum> 1406 <value>OFF 1407 <notes>Auto-white balance lock is disabled; the AWB 1408 algorithm is free to update its parameters if in AUTO 1409 mode.</notes></value> 1410 <value>ON 1411 <notes>Auto-white balance lock is enabled; the AWB 1412 algorithm will not update its parameters while the lock 1413 is active.</notes></value> 1414 </enum> 1415 <description>Whether auto-white balance (AWB) is currently locked to its 1416 latest calculated values.</description> 1417 <details> 1418 When set to `true` (ON), the AWB algorithm is locked to its latest parameters, 1419 and will not change color balance settings until the lock is set to `false` (OFF). 1420 1421 Since the camera device has a pipeline of in-flight requests, the settings that 1422 get locked do not necessarily correspond to the settings that were present in the 1423 latest capture result received from the camera device, since additional captures 1424 and AWB updates may have occurred even before the result was sent out. If an 1425 application is switching between automatic and manual control and wishes to eliminate 1426 any flicker during the switch, the following procedure is recommended: 1427 1428 1. Starting in auto-AWB mode: 1429 2. Lock AWB 1430 3. Wait for the first result to be output that has the AWB locked 1431 4. Copy AWB settings from that result into a request, set the request to manual AWB 1432 5. Submit the capture request, proceed to run manual AWB as desired. 1433 1434 Note that AWB lock is only meaningful when 1435 android.control.awbMode is in the AUTO mode; in other modes, 1436 AWB is already fixed to a specific setting. 1437 1438 Some LEGACY devices may not support ON; the value is then overridden to OFF. 1439 </details> 1440 <tag id="BC" /> 1441 </entry> 1442 <entry name="awbMode" type="byte" visibility="public" enum="true" 1443 hwlevel="legacy"> 1444 <enum> 1445 <value>OFF 1446 <notes> 1447 The camera device's auto-white balance routine is disabled. 1448 1449 The application-selected color transform matrix 1450 (android.colorCorrection.transform) and gains 1451 (android.colorCorrection.gains) are used by the camera 1452 device for manual white balance control. 1453 </notes> 1454 </value> 1455 <value>AUTO 1456 <notes> 1457 The camera device's auto-white balance routine is active. 1458 1459 The application's values for android.colorCorrection.transform 1460 and android.colorCorrection.gains are ignored. 1461 For devices that support the MANUAL_POST_PROCESSING capability, the 1462 values used by the camera device for the transform and gains 1463 will be available in the capture result for this request. 1464 </notes> 1465 </value> 1466 <value>INCANDESCENT 1467 <notes> 1468 The camera device's auto-white balance routine is disabled; 1469 the camera device uses incandescent light as the assumed scene 1470 illumination for white balance. 1471 1472 While the exact white balance transforms are up to the 1473 camera device, they will approximately match the CIE 1474 standard illuminant A. 1475 1476 The application's values for android.colorCorrection.transform 1477 and android.colorCorrection.gains are ignored. 1478 For devices that support the MANUAL_POST_PROCESSING capability, the 1479 values used by the camera device for the transform and gains 1480 will be available in the capture result for this request. 1481 </notes> 1482 </value> 1483 <value>FLUORESCENT 1484 <notes> 1485 The camera device's auto-white balance routine is disabled; 1486 the camera device uses fluorescent light as the assumed scene 1487 illumination for white balance. 1488 1489 While the exact white balance transforms are up to the 1490 camera device, they will approximately match the CIE 1491 standard illuminant F2. 1492 1493 The application's values for android.colorCorrection.transform 1494 and android.colorCorrection.gains are ignored. 1495 For devices that support the MANUAL_POST_PROCESSING capability, the 1496 values used by the camera device for the transform and gains 1497 will be available in the capture result for this request. 1498 </notes> 1499 </value> 1500 <value>WARM_FLUORESCENT 1501 <notes> 1502 The camera device's auto-white balance routine is disabled; 1503 the camera device uses warm fluorescent light as the assumed scene 1504 illumination for white balance. 1505 1506 While the exact white balance transforms are up to the 1507 camera device, they will approximately match the CIE 1508 standard illuminant F4. 1509 1510 The application's values for android.colorCorrection.transform 1511 and android.colorCorrection.gains are ignored. 1512 For devices that support the MANUAL_POST_PROCESSING capability, the 1513 values used by the camera device for the transform and gains 1514 will be available in the capture result for this request. 1515 </notes> 1516 </value> 1517 <value>DAYLIGHT 1518 <notes> 1519 The camera device's auto-white balance routine is disabled; 1520 the camera device uses daylight light as the assumed scene 1521 illumination for white balance. 1522 1523 While the exact white balance transforms are up to the 1524 camera device, they will approximately match the CIE 1525 standard illuminant D65. 1526 1527 The application's values for android.colorCorrection.transform 1528 and android.colorCorrection.gains are ignored. 1529 For devices that support the MANUAL_POST_PROCESSING capability, the 1530 values used by the camera device for the transform and gains 1531 will be available in the capture result for this request. 1532 </notes> 1533 </value> 1534 <value>CLOUDY_DAYLIGHT 1535 <notes> 1536 The camera device's auto-white balance routine is disabled; 1537 the camera device uses cloudy daylight light as the assumed scene 1538 illumination for white balance. 1539 1540 The application's values for android.colorCorrection.transform 1541 and android.colorCorrection.gains are ignored. 1542 For devices that support the MANUAL_POST_PROCESSING capability, the 1543 values used by the camera device for the transform and gains 1544 will be available in the capture result for this request. 1545 </notes> 1546 </value> 1547 <value>TWILIGHT 1548 <notes> 1549 The camera device's auto-white balance routine is disabled; 1550 the camera device uses twilight light as the assumed scene 1551 illumination for white balance. 1552 1553 The application's values for android.colorCorrection.transform 1554 and android.colorCorrection.gains are ignored. 1555 For devices that support the MANUAL_POST_PROCESSING capability, the 1556 values used by the camera device for the transform and gains 1557 will be available in the capture result for this request. 1558 </notes> 1559 </value> 1560 <value>SHADE 1561 <notes> 1562 The camera device's auto-white balance routine is disabled; 1563 the camera device uses shade light as the assumed scene 1564 illumination for white balance. 1565 1566 The application's values for android.colorCorrection.transform 1567 and android.colorCorrection.gains are ignored. 1568 For devices that support the MANUAL_POST_PROCESSING capability, the 1569 values used by the camera device for the transform and gains 1570 will be available in the capture result for this request. 1571 </notes> 1572 </value> 1573 </enum> 1574 <description>Whether auto-white balance (AWB) is currently setting the color 1575 transform fields, and what its illumination target 1576 is.</description> 1577 <range>android.control.awbAvailableModes</range> 1578 <details> 1579 This control is only effective if android.control.mode is AUTO. 1580 1581 When set to the AUTO mode, the camera device's auto-white balance 1582 routine is enabled, overriding the application's selected 1583 android.colorCorrection.transform, android.colorCorrection.gains and 1584 android.colorCorrection.mode. Note that when android.control.aeMode 1585 is OFF, the behavior of AWB is device dependent. It is recommended to 1586 also set AWB mode to OFF or lock AWB by using android.control.awbLock before 1587 setting AE mode to OFF. 1588 1589 When set to the OFF mode, the camera device's auto-white balance 1590 routine is disabled. The application manually controls the white 1591 balance by android.colorCorrection.transform, android.colorCorrection.gains 1592 and android.colorCorrection.mode. 1593 1594 When set to any other modes, the camera device's auto-white 1595 balance routine is disabled. The camera device uses each 1596 particular illumination target for white balance 1597 adjustment. The application's values for 1598 android.colorCorrection.transform, 1599 android.colorCorrection.gains and 1600 android.colorCorrection.mode are ignored. 1601 </details> 1602 <tag id="BC" /> 1603 </entry> 1604 <entry name="awbRegions" type="int32" visibility="public" 1605 optional="true" container="array" typedef="meteringRectangle"> 1606 <array> 1607 <size>5</size> 1608 <size>area_count</size> 1609 </array> 1610 <description>List of metering areas to use for auto-white-balance illuminant 1611 estimation.</description> 1612 <units>Pixel coordinates within android.sensor.info.activeArraySize or 1613 android.sensor.info.preCorrectionActiveArraySize depending on 1614 distortion correction capability and mode</units> 1615 <range>Coordinates must be between `[(0,0), (width, height))` of 1616 android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize 1617 depending on distortion correction capability and mode</range> 1618 <details> 1619 Not available if android.control.maxRegionsAwb is 0. 1620 Otherwise will always be present. 1621 1622 The maximum number of regions supported by the device is determined by the value 1623 of android.control.maxRegionsAwb. 1624 1625 For devices not supporting android.distortionCorrection.mode control, the coordinate 1626 system always follows that of android.sensor.info.activeArraySize, with (0,0) being 1627 the top-left pixel in the active pixel array, and 1628 (android.sensor.info.activeArraySize.width - 1, 1629 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1630 active pixel array. 1631 1632 For devices supporting android.distortionCorrection.mode control, the coordinate 1633 system depends on the mode being set. 1634 When the distortion correction mode is OFF, the coordinate system follows 1635 android.sensor.info.preCorrectionActiveArraySize, with 1636 `(0, 0)` being the top-left pixel of the pre-correction active array, and 1637 (android.sensor.info.preCorrectionActiveArraySize.width - 1, 1638 android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right 1639 pixel in the pre-correction active pixel array. 1640 When the distortion correction mode is not OFF, the coordinate system follows 1641 android.sensor.info.activeArraySize, with 1642 `(0, 0)` being the top-left pixel of the active array, and 1643 (android.sensor.info.activeArraySize.width - 1, 1644 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1645 active pixel array. 1646 1647 The weight must range from 0 to 1000, and represents a weight 1648 for every pixel in the area. This means that a large metering area 1649 with the same weight as a smaller area will have more effect in 1650 the metering result. Metering areas can partially overlap and the 1651 camera device will add the weights in the overlap region. 1652 1653 The weights are relative to weights of other white balance metering regions, so if 1654 only one region is used, all non-zero weights will have the same effect. A region with 1655 0 weight is ignored. 1656 1657 If all regions have 0 weight, then no specific metering area needs to be used by the 1658 camera device. 1659 1660 If the metering region is outside the used android.scaler.cropRegion returned in 1661 capture result metadata, the camera device will ignore the sections outside the crop 1662 region and output only the intersection rectangle as the metering region in the result 1663 metadata. If the region is entirely outside the crop region, it will be ignored and 1664 not reported in the result metadata. 1665 1666 When setting the AWB metering regions, the application must consider the additional 1667 crop resulted from the aspect ratio differences between the preview stream and 1668 android.scaler.cropRegion. For example, if the android.scaler.cropRegion is the full 1669 active array size with 4:3 aspect ratio, and the preview stream is 16:9, 1670 the boundary of AWB regions will be [0, y_crop] and 1671 [active_width, active_height - 2 * y_crop] rather than [0, 0] and 1672 [active_width, active_height], where y_crop is the additional crop due to aspect ratio 1673 mismatch. 1674 1675 Starting from API level 30, the coordinate system of activeArraySize or 1676 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 1677 pre-zoom field of view. This means that the same awbRegions values at different 1678 android.control.zoomRatio represent different parts of the scene. The awbRegions 1679 coordinates are relative to the activeArray/preCorrectionActiveArray representing the 1680 zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same 1681 awbRegions at different android.scaler.cropRegion still represent the same parts of 1682 the scene as they do before. See android.control.zoomRatio for details. Whether to use 1683 activeArraySize or preCorrectionActiveArraySize still depends on distortion correction 1684 mode. 1685 1686 For camera devices with the 1687 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 1688 capability or devices where 1689 {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 1690 lists android.sensor.pixelMode, 1691 android.sensor.info.activeArraySizeMaximumResolution / 1692 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 1693 coordinate system for requests where android.sensor.pixelMode is set to 1694 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 1695 </details> 1696 <ndk_details> 1697 The data representation is `int[5 * area_count]`. 1698 Every five elements represent a metering region of `(xmin, ymin, xmax, ymax, weight)`. 1699 The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and 1700 ymax. 1701 </ndk_details> 1702 <hal_details> 1703 The HAL level representation of MeteringRectangle[] is a 1704 int[5 * area_count]. 1705 Every five elements represent a metering region of 1706 (xmin, ymin, xmax, ymax, weight). 1707 The rectangle is defined to be inclusive on xmin and ymin, but 1708 exclusive on xmax and ymax. 1709 HAL must always report metering regions in the coordinate system of pre-correction 1710 active array. 1711 </hal_details> 1712 <tag id="BC" /> 1713 </entry> 1714 <entry name="captureIntent" type="byte" visibility="public" enum="true" 1715 hwlevel="legacy"> 1716 <enum> 1717 <value>CUSTOM 1718 <notes>The goal of this request doesn't fall into the other 1719 categories. The camera device will default to preview-like 1720 behavior.</notes></value> 1721 <value>PREVIEW 1722 <notes>This request is for a preview-like use case. 1723 1724 The precapture trigger may be used to start off a metering 1725 w/flash sequence. 1726 </notes></value> 1727 <value>STILL_CAPTURE 1728 <notes>This request is for a still capture-type 1729 use case. 1730 1731 If the flash unit is under automatic control, it may fire as needed. 1732 </notes></value> 1733 <value>VIDEO_RECORD 1734 <notes>This request is for a video recording 1735 use case.</notes></value> 1736 <value>VIDEO_SNAPSHOT 1737 <notes>This request is for a video snapshot (still 1738 image while recording video) use case. 1739 1740 The camera device should take the highest-quality image 1741 possible (given the other settings) without disrupting the 1742 frame rate of video recording. </notes></value> 1743 <value>ZERO_SHUTTER_LAG 1744 <notes>This request is for a ZSL usecase; the 1745 application will stream full-resolution images and 1746 reprocess one or several later for a final 1747 capture. 1748 </notes></value> 1749 <value>MANUAL 1750 <notes>This request is for manual capture use case where 1751 the applications want to directly control the capture parameters. 1752 1753 For example, the application may wish to manually control 1754 android.sensor.exposureTime, android.sensor.sensitivity, etc. 1755 </notes></value> 1756 <value hal_version="3.3">MOTION_TRACKING 1757 <notes>This request is for a motion tracking use case, where 1758 the application will use camera and inertial sensor data to 1759 locate and track objects in the world. 1760 1761 The camera device auto-exposure routine will limit the exposure time 1762 of the camera to no more than 20 milliseconds, to minimize motion blur. 1763 </notes></value> 1764 </enum> 1765 <description>Information to the camera device 3A (auto-exposure, 1766 auto-focus, auto-white balance) routines about the purpose 1767 of this capture, to help the camera device to decide optimal 3A 1768 strategy.</description> 1769 <details>This control (except for MANUAL) is only effective if 1770 `android.control.mode != OFF` and any 3A routine is active. 1771 1772 All intents are supported by all devices, except that: 1773 1774 * ZERO_SHUTTER_LAG will be supported if android.request.availableCapabilities contains 1775 PRIVATE_REPROCESSING or YUV_REPROCESSING. 1776 * MANUAL will be supported if android.request.availableCapabilities contains 1777 MANUAL_SENSOR. 1778 * MOTION_TRACKING will be supported if android.request.availableCapabilities contains 1779 MOTION_TRACKING. 1780 </details> 1781 <tag id="BC" /> 1782 </entry> 1783 <entry name="effectMode" type="byte" visibility="public" enum="true" 1784 hwlevel="legacy"> 1785 <enum> 1786 <value>OFF 1787 <notes> 1788 No color effect will be applied. 1789 </notes> 1790 </value> 1791 <value optional="true">MONO 1792 <notes> 1793 A "monocolor" effect where the image is mapped into 1794 a single color. 1795 1796 This will typically be grayscale. 1797 </notes> 1798 </value> 1799 <value optional="true">NEGATIVE 1800 <notes> 1801 A "photo-negative" effect where the image's colors 1802 are inverted. 1803 </notes> 1804 </value> 1805 <value optional="true">SOLARIZE 1806 <notes> 1807 A "solarisation" effect (Sabattier effect) where the 1808 image is wholly or partially reversed in 1809 tone. 1810 </notes> 1811 </value> 1812 <value optional="true">SEPIA 1813 <notes> 1814 A "sepia" effect where the image is mapped into warm 1815 gray, red, and brown tones. 1816 </notes> 1817 </value> 1818 <value optional="true">POSTERIZE 1819 <notes> 1820 A "posterization" effect where the image uses 1821 discrete regions of tone rather than a continuous 1822 gradient of tones. 1823 </notes> 1824 </value> 1825 <value optional="true">WHITEBOARD 1826 <notes> 1827 A "whiteboard" effect where the image is typically displayed 1828 as regions of white, with black or grey details. 1829 </notes> 1830 </value> 1831 <value optional="true">BLACKBOARD 1832 <notes> 1833 A "blackboard" effect where the image is typically displayed 1834 as regions of black, with white or grey details. 1835 </notes> 1836 </value> 1837 <value optional="true">AQUA 1838 <notes> 1839 An "aqua" effect where a blue hue is added to the image. 1840 </notes> 1841 </value> 1842 </enum> 1843 <description>A special color effect to apply.</description> 1844 <range>android.control.availableEffects</range> 1845 <details> 1846 When this mode is set, a color effect will be applied 1847 to images produced by the camera device. The interpretation 1848 and implementation of these color effects is left to the 1849 implementor of the camera device, and should not be 1850 depended on to be consistent (or present) across all 1851 devices. 1852 </details> 1853 <tag id="BC" /> 1854 </entry> 1855 <entry name="mode" type="byte" visibility="public" enum="true" 1856 hwlevel="legacy"> 1857 <enum> 1858 <value>OFF 1859 <notes>Full application control of pipeline. 1860 1861 All control by the device's metering and focusing (3A) 1862 routines is disabled, and no other settings in 1863 android.control.* have any effect, except that 1864 android.control.captureIntent may be used by the camera 1865 device to select post-processing values for processing 1866 blocks that do not allow for manual control, or are not 1867 exposed by the camera API. 1868 1869 However, the camera device's 3A routines may continue to 1870 collect statistics and update their internal state so that 1871 when control is switched to AUTO mode, good control values 1872 can be immediately applied. 1873 </notes></value> 1874 <value>AUTO 1875 <notes>Use settings for each individual 3A routine. 1876 1877 Manual control of capture parameters is disabled. All 1878 controls in android.control.* besides sceneMode take 1879 effect.</notes></value> 1880 <value optional="true">USE_SCENE_MODE 1881 <notes>Use a specific scene mode. 1882 1883 Enabling this disables control.aeMode, control.awbMode and 1884 control.afMode controls; the camera device will ignore 1885 those settings while USE_SCENE_MODE is active (except for 1886 FACE_PRIORITY scene mode). Other control entries are still active. 1887 This setting can only be used if scene mode is supported (i.e. 1888 android.control.availableSceneModes 1889 contain some modes other than DISABLED). 1890 1891 For extended scene modes such as BOKEH, please use USE_EXTENDED_SCENE_MODE instead. 1892 </notes></value> 1893 <value optional="true">OFF_KEEP_STATE 1894 <notes>Same as OFF mode, except that this capture will not be 1895 used by camera device background auto-exposure, auto-white balance and 1896 auto-focus algorithms (3A) to update their statistics. 1897 1898 Specifically, the 3A routines are locked to the last 1899 values set from a request with AUTO, OFF, or 1900 USE_SCENE_MODE, and any statistics or state updates 1901 collected from manual captures with OFF_KEEP_STATE will be 1902 discarded by the camera device. 1903 </notes></value> 1904 <value optional="true" hal_version="3.5">USE_EXTENDED_SCENE_MODE 1905 <notes>Use a specific extended scene mode. 1906 1907 When extended scene mode is on, the camera device may override certain control 1908 parameters, such as targetFpsRange, AE, AWB, and AF modes, to achieve best power and 1909 quality tradeoffs. Only the mandatory stream combinations of LIMITED hardware level 1910 are guaranteed. 1911 1912 This setting can only be used if extended scene mode is supported (i.e. 1913 android.control.availableExtendedSceneModes 1914 contains some modes other than DISABLED).</notes></value> 1915 </enum> 1916 <description>Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control 1917 routines.</description> 1918 <range>android.control.availableModes</range> 1919 <details> 1920 This is a top-level 3A control switch. When set to OFF, all 3A control 1921 by the camera device is disabled. The application must set the fields for 1922 capture parameters itself. 1923 1924 When set to AUTO, the individual algorithm controls in 1925 android.control.* are in effect, such as android.control.afMode. 1926 1927 When set to USE_SCENE_MODE or USE_EXTENDED_SCENE_MODE, the individual controls in 1928 android.control.* are mostly disabled, and the camera device 1929 implements one of the scene mode or extended scene mode settings (such as ACTION, 1930 SUNSET, PARTY, or BOKEH) as it wishes. The camera device scene mode 1931 3A settings are provided by {@link 1932 android.hardware.camera2.CaptureResult|ACameraCaptureSession_captureCallback_result 1933 capture results}. 1934 1935 When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference 1936 is that this frame will not be used by camera device background 3A statistics 1937 update, as if this frame is never captured. This mode can be used in the scenario 1938 where the application doesn't want a 3A manual control capture to affect 1939 the subsequent auto 3A capture results. 1940 </details> 1941 <tag id="BC" /> 1942 </entry> 1943 <entry name="sceneMode" type="byte" visibility="public" enum="true" 1944 hwlevel="legacy"> 1945 <enum> 1946 <value id="0">DISABLED 1947 <notes> 1948 Indicates that no scene modes are set for a given capture request. 1949 </notes> 1950 </value> 1951 <value>FACE_PRIORITY 1952 <notes>If face detection support exists, use face 1953 detection data for auto-focus, auto-white balance, and 1954 auto-exposure routines. 1955 1956 If face detection statistics are disabled 1957 (i.e. android.statistics.faceDetectMode is set to OFF), 1958 this should still operate correctly (but will not return 1959 face detection statistics to the framework). 1960 1961 Unlike the other scene modes, android.control.aeMode, 1962 android.control.awbMode, and android.control.afMode 1963 remain active when FACE_PRIORITY is set. 1964 </notes> 1965 </value> 1966 <value optional="true">ACTION 1967 <notes> 1968 Optimized for photos of quickly moving objects. 1969 1970 Similar to SPORTS. 1971 </notes> 1972 </value> 1973 <value optional="true">PORTRAIT 1974 <notes> 1975 Optimized for still photos of people. 1976 </notes> 1977 </value> 1978 <value optional="true">LANDSCAPE 1979 <notes> 1980 Optimized for photos of distant macroscopic objects. 1981 </notes> 1982 </value> 1983 <value optional="true">NIGHT 1984 <notes> 1985 Optimized for low-light settings. 1986 </notes> 1987 </value> 1988 <value optional="true">NIGHT_PORTRAIT 1989 <notes> 1990 Optimized for still photos of people in low-light 1991 settings. 1992 </notes> 1993 </value> 1994 <value optional="true">THEATRE 1995 <notes> 1996 Optimized for dim, indoor settings where flash must 1997 remain off. 1998 </notes> 1999 </value> 2000 <value optional="true">BEACH 2001 <notes> 2002 Optimized for bright, outdoor beach settings. 2003 </notes> 2004 </value> 2005 <value optional="true">SNOW 2006 <notes> 2007 Optimized for bright, outdoor settings containing snow. 2008 </notes> 2009 </value> 2010 <value optional="true">SUNSET 2011 <notes> 2012 Optimized for scenes of the setting sun. 2013 </notes> 2014 </value> 2015 <value optional="true">STEADYPHOTO 2016 <notes> 2017 Optimized to avoid blurry photos due to small amounts of 2018 device motion (for example: due to hand shake). 2019 </notes> 2020 </value> 2021 <value optional="true">FIREWORKS 2022 <notes> 2023 Optimized for nighttime photos of fireworks. 2024 </notes> 2025 </value> 2026 <value optional="true">SPORTS 2027 <notes> 2028 Optimized for photos of quickly moving people. 2029 2030 Similar to ACTION. 2031 </notes> 2032 </value> 2033 <value optional="true">PARTY 2034 <notes> 2035 Optimized for dim, indoor settings with multiple moving 2036 people. 2037 </notes> 2038 </value> 2039 <value optional="true">CANDLELIGHT 2040 <notes> 2041 Optimized for dim settings where the main light source 2042 is a candle. 2043 </notes> 2044 </value> 2045 <value optional="true">BARCODE 2046 <notes> 2047 Optimized for accurately capturing a photo of barcode 2048 for use by camera applications that wish to read the 2049 barcode value. 2050 </notes> 2051 </value> 2052 <value deprecated="true" optional="true" visibility="java_public">HIGH_SPEED_VIDEO 2053 <notes> 2054 This is deprecated, please use {@link 2055 android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession} 2056 and {@link 2057 android.hardware.camera2.CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList} 2058 for high speed video recording. 2059 2060 Optimized for high speed video recording (frame rate >=60fps) use case. 2061 2062 The supported high speed video sizes and fps ranges are specified in 2063 android.control.availableHighSpeedVideoConfigurations. To get desired 2064 output frame rates, the application is only allowed to select video size 2065 and fps range combinations listed in this static metadata. The fps range 2066 can be control via android.control.aeTargetFpsRange. 2067 2068 In this mode, the camera device will override aeMode, awbMode, and afMode to 2069 ON, ON, and CONTINUOUS_VIDEO, respectively. All post-processing block mode 2070 controls will be overridden to be FAST. Therefore, no manual control of capture 2071 and post-processing parameters is possible. All other controls operate the 2072 same as when android.control.mode == AUTO. This means that all other 2073 android.control.* fields continue to work, such as 2074 2075 * android.control.aeTargetFpsRange 2076 * android.control.aeExposureCompensation 2077 * android.control.aeLock 2078 * android.control.awbLock 2079 * android.control.effectMode 2080 * android.control.aeRegions 2081 * android.control.afRegions 2082 * android.control.awbRegions 2083 * android.control.afTrigger 2084 * android.control.aePrecaptureTrigger 2085 * android.control.zoomRatio 2086 2087 Outside of android.control.*, the following controls will work: 2088 2089 * android.flash.mode (automatic flash for still capture will not work since aeMode is ON) 2090 * android.lens.opticalStabilizationMode (if it is supported) 2091 * android.scaler.cropRegion 2092 * android.statistics.faceDetectMode 2093 2094 For high speed recording use case, the actual maximum supported frame rate may 2095 be lower than what camera can output, depending on the destination Surfaces for 2096 the image data. For example, if the destination surface is from video encoder, 2097 the application need check if the video encoder is capable of supporting the 2098 high frame rate for a given video size, or it will end up with lower recording 2099 frame rate. If the destination surface is from preview window, the preview frame 2100 rate will be bounded by the screen refresh rate. 2101 2102 The camera device will only support up to 2 output high speed streams 2103 (processed non-stalling format defined in android.request.maxNumOutputStreams) 2104 in this mode. This control will be effective only if all of below conditions are true: 2105 2106 * The application created no more than maxNumHighSpeedStreams processed non-stalling 2107 format output streams, where maxNumHighSpeedStreams is calculated as 2108 min(2, android.request.maxNumOutputStreams[Processed (but not-stalling)]). 2109 * The stream sizes are selected from the sizes reported by 2110 android.control.availableHighSpeedVideoConfigurations. 2111 * No processed non-stalling or raw streams are configured. 2112 2113 When above conditions are NOT satisfied, the controls of this mode and 2114 android.control.aeTargetFpsRange will be ignored by the camera device, 2115 the camera device will fall back to android.control.mode `==` AUTO, 2116 and the returned capture result metadata will give the fps range chosen 2117 by the camera device. 2118 2119 Switching into or out of this mode may trigger some camera ISP/sensor 2120 reconfigurations, which may introduce extra latency. It is recommended that 2121 the application avoids unnecessary scene mode switch as much as possible. 2122 </notes> 2123 </value> 2124 <value optional="true">HDR 2125 <notes> 2126 Turn on a device-specific high dynamic range (HDR) mode. 2127 2128 In this scene mode, the camera device captures images 2129 that keep a larger range of scene illumination levels 2130 visible in the final image. For example, when taking a 2131 picture of a object in front of a bright window, both 2132 the object and the scene through the window may be 2133 visible when using HDR mode, while in normal AUTO mode, 2134 one or the other may be poorly exposed. As a tradeoff, 2135 HDR mode generally takes much longer to capture a single 2136 image, has no user control, and may have other artifacts 2137 depending on the HDR method used. 2138 2139 Therefore, HDR captures operate at a much slower rate 2140 than regular captures. 2141 2142 In this mode, on LIMITED or FULL devices, when a request 2143 is made with a android.control.captureIntent of 2144 STILL_CAPTURE, the camera device will capture an image 2145 using a high dynamic range capture technique. On LEGACY 2146 devices, captures that target a JPEG-format output will 2147 be captured with HDR, and the capture intent is not 2148 relevant. 2149 2150 The HDR capture may involve the device capturing a burst 2151 of images internally and combining them into one, or it 2152 may involve the device using specialized high dynamic 2153 range capture hardware. In all cases, a single image is 2154 produced in response to a capture request submitted 2155 while in HDR mode. 2156 2157 Since substantial post-processing is generally needed to 2158 produce an HDR image, only YUV, PRIVATE, and JPEG 2159 outputs are supported for LIMITED/FULL device HDR 2160 captures, and only JPEG outputs are supported for LEGACY 2161 HDR captures. Using a RAW output for HDR capture is not 2162 supported. 2163 2164 Some devices may also support always-on HDR, which 2165 applies HDR processing at full frame rate. For these 2166 devices, intents other than STILL_CAPTURE will also 2167 produce an HDR output with no frame rate impact compared 2168 to normal operation, though the quality may be lower 2169 than for STILL_CAPTURE intents. 2170 2171 If SCENE_MODE_HDR is used with unsupported output types 2172 or capture intents, the images captured will be as if 2173 the SCENE_MODE was not enabled at all. 2174 </notes> 2175 </value> 2176 <value optional="true" visibility="hidden">FACE_PRIORITY_LOW_LIGHT 2177 <notes>Same as FACE_PRIORITY scene mode, except that the camera 2178 device will choose higher sensitivity values (android.sensor.sensitivity) 2179 under low light conditions. 2180 2181 The camera device may be tuned to expose the images in a reduced 2182 sensitivity range to produce the best quality images. For example, 2183 if the android.sensor.info.sensitivityRange gives range of [100, 1600], 2184 the camera device auto-exposure routine tuning process may limit the actual 2185 exposure sensitivity range to [100, 1200] to ensure that the noise level isn't 2186 excessive in order to preserve the image quality. Under this situation, the image under 2187 low light may be under-exposed when the sensor max exposure time (bounded by the 2188 android.control.aeTargetFpsRange when android.control.aeMode is one of the 2189 ON_* modes) and effective max sensitivity are reached. This scene mode allows the 2190 camera device auto-exposure routine to increase the sensitivity up to the max 2191 sensitivity specified by android.sensor.info.sensitivityRange when the scene is too 2192 dark and the max exposure time is reached. The captured images may be noisier 2193 compared with the images captured in normal FACE_PRIORITY mode; therefore, it is 2194 recommended that the application only use this scene mode when it is capable of 2195 reducing the noise level of the captured images. 2196 2197 Unlike the other scene modes, android.control.aeMode, 2198 android.control.awbMode, and android.control.afMode 2199 remain active when FACE_PRIORITY_LOW_LIGHT is set. 2200 </notes> 2201 </value> 2202 <value optional="true" visibility="hidden" id="100">DEVICE_CUSTOM_START 2203 <notes> 2204 Scene mode values within the range of 2205 `[DEVICE_CUSTOM_START, DEVICE_CUSTOM_END]` are reserved for device specific 2206 customized scene modes. 2207 </notes> 2208 </value> 2209 <value optional="true" visibility="hidden" id="127">DEVICE_CUSTOM_END 2210 <notes> 2211 Scene mode values within the range of 2212 `[DEVICE_CUSTOM_START, DEVICE_CUSTOM_END]` are reserved for device specific 2213 customized scene modes. 2214 </notes> 2215 </value> 2216 </enum> 2217 <description> 2218 Control for which scene mode is currently active. 2219 </description> 2220 <range>android.control.availableSceneModes</range> 2221 <details> 2222 Scene modes are custom camera modes optimized for a certain set of conditions and 2223 capture settings. 2224 2225 This is the mode that that is active when 2226 `android.control.mode == USE_SCENE_MODE`. Aside from FACE_PRIORITY, these modes will 2227 disable android.control.aeMode, android.control.awbMode, and android.control.afMode 2228 while in use. 2229 2230 The interpretation and implementation of these scene modes is left 2231 to the implementor of the camera device. Their behavior will not be 2232 consistent across all devices, and any given device may only implement 2233 a subset of these modes. 2234 </details> 2235 <hal_details> 2236 HAL implementations that include scene modes are expected to provide 2237 the per-scene settings to use for android.control.aeMode, 2238 android.control.awbMode, and android.control.afMode in 2239 android.control.sceneModeOverrides. 2240 2241 For HIGH_SPEED_VIDEO mode, if it is included in android.control.availableSceneModes, the 2242 HAL must list supported video size and fps range in 2243 android.control.availableHighSpeedVideoConfigurations. For a given size, e.g. 1280x720, 2244 if the HAL has two different sensor configurations for normal streaming mode and high 2245 speed streaming, when this scene mode is set/reset in a sequence of capture requests, the 2246 HAL may have to switch between different sensor modes. This mode is deprecated in legacy 2247 HAL3.3, to support high speed video recording, please implement 2248 android.control.availableHighSpeedVideoConfigurations and CONSTRAINED_HIGH_SPEED_VIDEO 2249 capability defined in android.request.availableCapabilities. 2250 </hal_details> 2251 <tag id="BC" /> 2252 </entry> 2253 <entry name="videoStabilizationMode" type="byte" visibility="public" 2254 enum="true" hwlevel="legacy"> 2255 <enum> 2256 <value>OFF 2257 <notes> 2258 Video stabilization is disabled. 2259 </notes></value> 2260 <value>ON 2261 <notes> 2262 Video stabilization is enabled. 2263 </notes></value> 2264 <value optional="true" hal_version="3.8">PREVIEW_STABILIZATION 2265 <notes> 2266 Preview stabilization, where the preview in addition to all other non-RAW streams are 2267 stabilized with the same quality of stabilization, is enabled. This mode aims to give 2268 clients a 'what you see is what you get' effect. In this mode, the FoV reduction will 2269 be a maximum of 20 % both horizontally and vertically 2270 (10% from left, right, top, bottom) for the given zoom ratio / crop region. 2271 The resultant FoV will also be the same across all processed streams 2272 (that have the same aspect ratio). 2273 </notes></value> 2274 </enum> 2275 <description>Whether video stabilization is 2276 active.</description> 2277 <details> 2278 Video stabilization automatically warps images from 2279 the camera in order to stabilize motion between consecutive frames. 2280 2281 If enabled, video stabilization can modify the 2282 android.scaler.cropRegion to keep the video stream stabilized. 2283 2284 Switching between different video stabilization modes may take several 2285 frames to initialize, the camera device will report the current mode 2286 in capture result metadata. For example, When "ON" mode is requested, 2287 the video stabilization modes in the first several capture results may 2288 still be "OFF", and it will become "ON" when the initialization is 2289 done. 2290 2291 In addition, not all recording sizes or frame rates may be supported for 2292 stabilization by a device that reports stabilization support. It is guaranteed 2293 that an output targeting a MediaRecorder or MediaCodec will be stabilized if 2294 the recording resolution is less than or equal to 1920 x 1080 (width less than 2295 or equal to 1920, height less than or equal to 1080), and the recording 2296 frame rate is less than or equal to 30fps. At other sizes, the CaptureResult 2297 android.control.videoStabilizationMode field will return 2298 OFF if the recording output is not stabilized, or if there are no output 2299 Surface types that can be stabilized. 2300 2301 The application is strongly recommended to call 2302 {@link android.hardware.camera2.params.SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters} 2303 with the desired video stabilization mode before creating the capture session. 2304 Video stabilization mode is a session parameter on many devices. Specifying 2305 it at session creation time helps avoid reconfiguration delay caused by difference 2306 between the default value and the first CaptureRequest. 2307 2308 If a camera device supports both this mode and OIS 2309 (android.lens.opticalStabilizationMode), turning both modes on may 2310 produce undesirable interaction, so it is recommended not to enable 2311 both at the same time. 2312 2313 If video stabilization is set to "PREVIEW_STABILIZATION", 2314 android.lens.opticalStabilizationMode is overridden. The camera sub-system may choose 2315 to turn on hardware based image stabilization in addition to software based stabilization 2316 if it deems that appropriate. 2317 This key may be a part of the available session keys, which camera clients may 2318 query via 2319 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys|ACameraManager_getCameraCharacteristics}. 2320 If this is the case, changing this key over the life-time of a capture session may 2321 cause delays / glitches. 2322 2323 </details> 2324 <hal_details> 2325 When this key is set to "PREVIEW_STABILIZATION", 2326 for non-stalling buffers returned without errors, the time interval between notify readout 2327 timestamp and when buffers are returned to the camera framework, must be no more than 1 2328 extra frame interval, relative to the case where this key is set to "OFF". 2329 2330 This is in order for look-ahead time period to be short enough 2331 for preview to match video recording for real-time usage. 2332 </hal_details> 2333 <tag id="BC" /> 2334 </entry> 2335 </controls> 2336 <static> 2337 <entry name="aeAvailableAntibandingModes" type="byte" visibility="public" 2338 type_notes="list of enums" container="array" typedef="enumList" 2339 hwlevel="legacy"> 2340 <array> 2341 <size>n</size> 2342 </array> 2343 <description> 2344 List of auto-exposure antibanding modes for android.control.aeAntibandingMode that are 2345 supported by this camera device. 2346 </description> 2347 <range>Any value listed in android.control.aeAntibandingMode</range> 2348 <details> 2349 Not all of the auto-exposure anti-banding modes may be 2350 supported by a given camera device. This field lists the 2351 valid anti-banding modes that the application may request 2352 for this camera device with the 2353 android.control.aeAntibandingMode control. 2354 </details> 2355 <tag id="BC" /> 2356 </entry> 2357 <entry name="aeAvailableModes" type="byte" visibility="public" 2358 type_notes="list of enums" container="array" typedef="enumList" 2359 hwlevel="legacy"> 2360 <array> 2361 <size>n</size> 2362 </array> 2363 <description> 2364 List of auto-exposure modes for android.control.aeMode that are supported by this camera 2365 device. 2366 </description> 2367 <range>Any value listed in android.control.aeMode</range> 2368 <details> 2369 Not all the auto-exposure modes may be supported by a 2370 given camera device, especially if no flash unit is 2371 available. This entry lists the valid modes for 2372 android.control.aeMode for this camera device. 2373 2374 All camera devices support ON, and all camera devices with flash 2375 units support ON_AUTO_FLASH and ON_ALWAYS_FLASH. 2376 2377 FULL mode camera devices always support OFF mode, 2378 which enables application control of camera exposure time, 2379 sensitivity, and frame duration. 2380 2381 LEGACY mode camera devices never support OFF mode. 2382 LIMITED mode devices support OFF if they support the MANUAL_SENSOR 2383 capability. 2384 </details> 2385 <tag id="BC" /> 2386 </entry> 2387 <entry name="aeAvailableTargetFpsRanges" type="int32" visibility="public" 2388 type_notes="list of pairs of frame rates" 2389 container="array" typedef="rangeInt" 2390 hwlevel="legacy"> 2391 <array> 2392 <size>2</size> 2393 <size>n</size> 2394 </array> 2395 <description>List of frame rate ranges for android.control.aeTargetFpsRange supported by 2396 this camera device.</description> 2397 <units>Frames per second (FPS)</units> 2398 <details> 2399 For devices at the LEGACY level or above: 2400 2401 * For constant-framerate recording, for each normal 2402 {@link android.media.CamcorderProfile CamcorderProfile}, that is, a 2403 {@link android.media.CamcorderProfile CamcorderProfile} that has 2404 {@link android.media.CamcorderProfile#quality quality} in 2405 the range [{@link android.media.CamcorderProfile#QUALITY_LOW QUALITY_LOW}, 2406 {@link android.media.CamcorderProfile#QUALITY_2160P QUALITY_2160P}], if the profile is 2407 supported by the device and has 2408 {@link android.media.CamcorderProfile#videoFrameRate videoFrameRate} `x`, this list will 2409 always include (`x`,`x`). 2410 2411 * Also, a camera device must either not support any 2412 {@link android.media.CamcorderProfile CamcorderProfile}, 2413 or support at least one 2414 normal {@link android.media.CamcorderProfile CamcorderProfile} that has 2415 {@link android.media.CamcorderProfile#videoFrameRate videoFrameRate} `x` >= 24. 2416 2417 For devices at the LIMITED level or above: 2418 2419 * For devices that advertise NIR color filter arrangement in 2420 android.sensor.info.colorFilterArrangement, this list will always include 2421 (`max`, `max`) where `max` = the maximum output frame rate of the maximum YUV_420_888 2422 output size. 2423 * For devices advertising any color filter arrangement other than NIR, or devices not 2424 advertising color filter arrangement, this list will always include (`min`, `max`) and 2425 (`max`, `max`) where `min` <= 15 and `max` = the maximum output frame rate of the 2426 maximum YUV_420_888 output size. 2427 2428 </details> 2429 <hal_details> 2430 HAL must make sure the lower bound and upper bound of each supported targetFpsRange can 2431 be reached. For example, if HAL supports an aeTargetFpsRange of (15, 30), when set by the 2432 application, the camera must be able to reach 15fps in sufficient dark scenes. This way 2433 the application knows the exact range of frame rate it can expect. 2434 </hal_details> 2435 <tag id="BC" /> 2436 </entry> 2437 <entry name="aeCompensationRange" type="int32" visibility="public" 2438 container="array" typedef="rangeInt" 2439 hwlevel="legacy"> 2440 <array> 2441 <size>2</size> 2442 </array> 2443 <description>Maximum and minimum exposure compensation values for 2444 android.control.aeExposureCompensation, in counts of android.control.aeCompensationStep, 2445 that are supported by this camera device.</description> 2446 <range> 2447 Range [0,0] indicates that exposure compensation is not supported. 2448 2449 For LIMITED and FULL devices, range must follow below requirements if exposure 2450 compensation is supported (`range != [0, 0]`): 2451 2452 `Min.exposure compensation * android.control.aeCompensationStep <= -2 EV` 2453 2454 `Max.exposure compensation * android.control.aeCompensationStep >= 2 EV` 2455 2456 LEGACY devices may support a smaller range than this. 2457 </range> 2458 <tag id="BC" /> 2459 </entry> 2460 <entry name="aeCompensationStep" type="rational" visibility="public" 2461 hwlevel="legacy"> 2462 <description>Smallest step by which the exposure compensation 2463 can be changed.</description> 2464 <units>Exposure Value (EV)</units> 2465 <details> 2466 This is the unit for android.control.aeExposureCompensation. For example, if this key has 2467 a value of `1/2`, then a setting of `-2` for android.control.aeExposureCompensation means 2468 that the target EV offset for the auto-exposure routine is -1 EV. 2469 2470 One unit of EV compensation changes the brightness of the captured image by a factor 2471 of two. +1 EV doubles the image brightness, while -1 EV halves the image brightness. 2472 </details> 2473 <hal_details> 2474 This must be less than or equal to 1/2. 2475 </hal_details> 2476 <tag id="BC" /> 2477 </entry> 2478 <entry name="afAvailableModes" type="byte" visibility="public" 2479 type_notes="List of enums" container="array" typedef="enumList" 2480 hwlevel="legacy"> 2481 <array> 2482 <size>n</size> 2483 </array> 2484 <description> 2485 List of auto-focus (AF) modes for android.control.afMode that are 2486 supported by this camera device. 2487 </description> 2488 <range>Any value listed in android.control.afMode</range> 2489 <details> 2490 Not all the auto-focus modes may be supported by a 2491 given camera device. This entry lists the valid modes for 2492 android.control.afMode for this camera device. 2493 2494 All LIMITED and FULL mode camera devices will support OFF mode, and all 2495 camera devices with adjustable focuser units 2496 (`android.lens.info.minimumFocusDistance > 0`) will support AUTO mode. 2497 2498 LEGACY devices will support OFF mode only if they support 2499 focusing to infinity (by also setting android.lens.focusDistance to 2500 `0.0f`). 2501 </details> 2502 <tag id="BC" /> 2503 </entry> 2504 <entry name="availableEffects" type="byte" visibility="public" 2505 type_notes="List of enums (android.control.effectMode)." container="array" 2506 typedef="enumList" hwlevel="legacy"> 2507 <array> 2508 <size>n</size> 2509 </array> 2510 <description> 2511 List of color effects for android.control.effectMode that are supported by this camera 2512 device. 2513 </description> 2514 <range>Any value listed in android.control.effectMode</range> 2515 <details> 2516 This list contains the color effect modes that can be applied to 2517 images produced by the camera device. 2518 Implementations are not expected to be consistent across all devices. 2519 If no color effect modes are available for a device, this will only list 2520 OFF. 2521 2522 A color effect will only be applied if 2523 android.control.mode != OFF. OFF is always included in this list. 2524 2525 This control has no effect on the operation of other control routines such 2526 as auto-exposure, white balance, or focus. 2527 </details> 2528 <tag id="BC" /> 2529 </entry> 2530 <entry name="availableSceneModes" type="byte" visibility="public" 2531 type_notes="List of enums (android.control.sceneMode)." 2532 container="array" typedef="enumList" hwlevel="legacy"> 2533 <array> 2534 <size>n</size> 2535 </array> 2536 <description> 2537 List of scene modes for android.control.sceneMode that are supported by this camera 2538 device. 2539 </description> 2540 <range>Any value listed in android.control.sceneMode</range> 2541 <details> 2542 This list contains scene modes that can be set for the camera device. 2543 Only scene modes that have been fully implemented for the 2544 camera device may be included here. Implementations are not expected 2545 to be consistent across all devices. 2546 2547 If no scene modes are supported by the camera device, this 2548 will be set to DISABLED. Otherwise DISABLED will not be listed. 2549 2550 FACE_PRIORITY is always listed if face detection is 2551 supported (i.e.`android.statistics.info.maxFaceCount > 2552 0`). 2553 </details> 2554 <tag id="BC" /> 2555 </entry> 2556 <entry name="availableVideoStabilizationModes" type="byte" 2557 visibility="public" type_notes="List of enums." container="array" 2558 typedef="enumList" hwlevel="legacy"> 2559 <array> 2560 <size>n</size> 2561 </array> 2562 <description> 2563 List of video stabilization modes for android.control.videoStabilizationMode 2564 that are supported by this camera device. 2565 </description> 2566 <range>Any value listed in android.control.videoStabilizationMode</range> 2567 <details> 2568 OFF will always be listed. 2569 </details> 2570 <tag id="BC" /> 2571 </entry> 2572 <entry name="awbAvailableModes" type="byte" visibility="public" 2573 type_notes="List of enums" 2574 container="array" typedef="enumList" hwlevel="legacy"> 2575 <array> 2576 <size>n</size> 2577 </array> 2578 <description> 2579 List of auto-white-balance modes for android.control.awbMode that are supported by this 2580 camera device. 2581 </description> 2582 <range>Any value listed in android.control.awbMode</range> 2583 <details> 2584 Not all the auto-white-balance modes may be supported by a 2585 given camera device. This entry lists the valid modes for 2586 android.control.awbMode for this camera device. 2587 2588 All camera devices will support ON mode. 2589 2590 Camera devices that support the MANUAL_POST_PROCESSING capability will always support OFF 2591 mode, which enables application control of white balance, by using 2592 android.colorCorrection.transform and android.colorCorrection.gains 2593 (android.colorCorrection.mode must be set to TRANSFORM_MATRIX). This includes all FULL 2594 mode camera devices. 2595 </details> 2596 <tag id="BC" /> 2597 </entry> 2598 <entry name="maxRegions" type="int32" visibility="ndk_public" 2599 container="array" hwlevel="legacy"> 2600 <array> 2601 <size>3</size> 2602 </array> 2603 <description> 2604 List of the maximum number of regions that can be used for metering in 2605 auto-exposure (AE), auto-white balance (AWB), and auto-focus (AF); 2606 this corresponds to the maximum number of elements in 2607 android.control.aeRegions, android.control.awbRegions, 2608 and android.control.afRegions. 2609 </description> 2610 <range> 2611 Value must be &gt;= 0 for each element. For full-capability devices 2612 this value must be &gt;= 1 for AE and AF. The order of the elements is: 2613 `(AE, AWB, AF)`.</range> 2614 <tag id="BC" /> 2615 </entry> 2616 <entry name="maxRegionsAe" type="int32" visibility="java_public" 2617 synthetic="true" hwlevel="legacy"> 2618 <description> 2619 The maximum number of metering regions that can be used by the auto-exposure (AE) 2620 routine. 2621 </description> 2622 <range>Value will be &gt;= 0. For FULL-capability devices, this 2623 value will be &gt;= 1. 2624 </range> 2625 <details> 2626 This corresponds to the maximum allowed number of elements in 2627 android.control.aeRegions. 2628 </details> 2629 <hal_details>This entry is private to the framework. Fill in 2630 maxRegions to have this entry be automatically populated. 2631 </hal_details> 2632 </entry> 2633 <entry name="maxRegionsAwb" type="int32" visibility="java_public" 2634 synthetic="true" hwlevel="legacy"> 2635 <description> 2636 The maximum number of metering regions that can be used by the auto-white balance (AWB) 2637 routine. 2638 </description> 2639 <range>Value will be &gt;= 0. 2640 </range> 2641 <details> 2642 This corresponds to the maximum allowed number of elements in 2643 android.control.awbRegions. 2644 </details> 2645 <hal_details>This entry is private to the framework. Fill in 2646 maxRegions to have this entry be automatically populated. 2647 </hal_details> 2648 </entry> 2649 <entry name="maxRegionsAf" type="int32" visibility="java_public" 2650 synthetic="true" hwlevel="legacy"> 2651 <description> 2652 The maximum number of metering regions that can be used by the auto-focus (AF) routine. 2653 </description> 2654 <range>Value will be &gt;= 0. For FULL-capability devices, this 2655 value will be &gt;= 1. 2656 </range> 2657 <details> 2658 This corresponds to the maximum allowed number of elements in 2659 android.control.afRegions. 2660 </details> 2661 <hal_details>This entry is private to the framework. Fill in 2662 maxRegions to have this entry be automatically populated. 2663 </hal_details> 2664 </entry> 2665 <entry name="sceneModeOverrides" type="byte" visibility="system" 2666 container="array" hwlevel="limited"> 2667 <array> 2668 <size>3</size> 2669 <size>length(availableSceneModes)</size> 2670 </array> 2671 <description> 2672 Ordered list of auto-exposure, auto-white balance, and auto-focus 2673 settings to use with each available scene mode. 2674 </description> 2675 <range> 2676 For each available scene mode, the list must contain three 2677 entries containing the android.control.aeMode, 2678 android.control.awbMode, and android.control.afMode values used 2679 by the camera device. The entry order is `(aeMode, awbMode, afMode)` 2680 where aeMode has the lowest index position. 2681 </range> 2682 <details> 2683 When a scene mode is enabled, the camera device is expected 2684 to override android.control.aeMode, android.control.awbMode, 2685 and android.control.afMode with its preferred settings for 2686 that scene mode. 2687 2688 The order of this list matches that of availableSceneModes, 2689 with 3 entries for each mode. The overrides listed 2690 for FACE_PRIORITY and FACE_PRIORITY_LOW_LIGHT (if supported) are ignored, 2691 since for that mode the application-set android.control.aeMode, 2692 android.control.awbMode, and android.control.afMode values are 2693 used instead, matching the behavior when android.control.mode 2694 is set to AUTO. It is recommended that the FACE_PRIORITY and 2695 FACE_PRIORITY_LOW_LIGHT (if supported) overrides should be set to 0. 2696 2697 For example, if availableSceneModes contains 2698 `(FACE_PRIORITY, ACTION, NIGHT)`, then the camera framework 2699 expects sceneModeOverrides to have 9 entries formatted like: 2700 `(0, 0, 0, ON_AUTO_FLASH, AUTO, CONTINUOUS_PICTURE, 2701 ON_AUTO_FLASH, INCANDESCENT, AUTO)`. 2702 </details> 2703 <hal_details> 2704 To maintain backward compatibility, this list will be made available 2705 in the static metadata of the camera service. The camera service will 2706 use these values to set android.control.aeMode, 2707 android.control.awbMode, and android.control.afMode when using a scene 2708 mode other than FACE_PRIORITY and FACE_PRIORITY_LOW_LIGHT (if supported). 2709 </hal_details> 2710 <tag id="BC" /> 2711 </entry> 2712 </static> 2713 <dynamic> 2714 <entry name="aePrecaptureId" type="int32" visibility="system" deprecated="true"> 2715 <description>The ID sent with the latest 2716 CAMERA2_TRIGGER_PRECAPTURE_METERING call</description> 2717 <deprecation_description> 2718 Removed in camera HAL v3 2719 </deprecation_description> 2720 <details>Must be 0 if no 2721 CAMERA2_TRIGGER_PRECAPTURE_METERING trigger received yet 2722 by HAL. Always updated even if AE algorithm ignores the 2723 trigger</details> 2724 </entry> 2725 <clone entry="android.control.aeAntibandingMode" kind="controls"> 2726 </clone> 2727 <clone entry="android.control.aeExposureCompensation" kind="controls"> 2728 </clone> 2729 <clone entry="android.control.aeLock" kind="controls"> 2730 </clone> 2731 <clone entry="android.control.aeMode" kind="controls"> 2732 </clone> 2733 <clone entry="android.control.aeRegions" kind="controls"> 2734 </clone> 2735 <clone entry="android.control.aeTargetFpsRange" kind="controls"> 2736 </clone> 2737 <clone entry="android.control.aePrecaptureTrigger" kind="controls"> 2738 </clone> 2739 <entry name="aeState" type="byte" visibility="public" enum="true" 2740 hwlevel="limited"> 2741 <enum> 2742 <value>INACTIVE 2743 <notes>AE is off or recently reset. 2744 2745 When a camera device is opened, it starts in 2746 this state. This is a transient state, the camera device may skip reporting 2747 this state in capture result.</notes></value> 2748 <value>SEARCHING 2749 <notes>AE doesn't yet have a good set of control values 2750 for the current scene. 2751 2752 This is a transient state, the camera device may skip 2753 reporting this state in capture result.</notes></value> 2754 <value>CONVERGED 2755 <notes>AE has a good set of control values for the 2756 current scene.</notes></value> 2757 <value>LOCKED 2758 <notes>AE has been locked.</notes></value> 2759 <value>FLASH_REQUIRED 2760 <notes>AE has a good set of control values, but flash 2761 needs to be fired for good quality still 2762 capture.</notes></value> 2763 <value>PRECAPTURE 2764 <notes>AE has been asked to do a precapture sequence 2765 and is currently executing it. 2766 2767 Precapture can be triggered through setting 2768 android.control.aePrecaptureTrigger to START. Currently 2769 active and completed (if it causes camera device internal AE lock) precapture 2770 metering sequence can be canceled through setting 2771 android.control.aePrecaptureTrigger to CANCEL. 2772 2773 Once PRECAPTURE completes, AE will transition to CONVERGED 2774 or FLASH_REQUIRED as appropriate. This is a transient 2775 state, the camera device may skip reporting this state in 2776 capture result.</notes></value> 2777 </enum> 2778 <description>Current state of the auto-exposure (AE) algorithm.</description> 2779 <details>Switching between or enabling AE modes (android.control.aeMode) always 2780 resets the AE state to INACTIVE. Similarly, switching between android.control.mode, 2781 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2782 the algorithm states to INACTIVE. 2783 2784 The camera device can do several state transitions between two results, if it is 2785 allowed by the state transition table. For example: INACTIVE may never actually be 2786 seen in a result. 2787 2788 The state in the result is the state for this image (in sync with this image): if 2789 AE state becomes CONVERGED, then the image data associated with this result should 2790 be good to use. 2791 2792 Below are state transition tables for different AE modes. 2793 2794 State | Transition Cause | New State | Notes 2795 :------------:|:----------------:|:---------:|:-----------------------: 2796 INACTIVE | | INACTIVE | Camera device auto exposure algorithm is disabled 2797 2798 When android.control.aeMode is AE_MODE_ON*: 2799 2800 State | Transition Cause | New State | Notes 2801 :-------------:|:--------------------------------------------:|:--------------:|:-----------------: 2802 INACTIVE | Camera device initiates AE scan | SEARCHING | Values changing 2803 INACTIVE | android.control.aeLock is ON | LOCKED | Values locked 2804 SEARCHING | Camera device finishes AE scan | CONVERGED | Good values, not changing 2805 SEARCHING | Camera device finishes AE scan | FLASH_REQUIRED | Converged but too dark w/o flash 2806 SEARCHING | android.control.aeLock is ON | LOCKED | Values locked 2807 CONVERGED | Camera device initiates AE scan | SEARCHING | Values changing 2808 CONVERGED | android.control.aeLock is ON | LOCKED | Values locked 2809 FLASH_REQUIRED | Camera device initiates AE scan | SEARCHING | Values changing 2810 FLASH_REQUIRED | android.control.aeLock is ON | LOCKED | Values locked 2811 LOCKED | android.control.aeLock is OFF | SEARCHING | Values not good after unlock 2812 LOCKED | android.control.aeLock is OFF | CONVERGED | Values good after unlock 2813 LOCKED | android.control.aeLock is OFF | FLASH_REQUIRED | Exposure good, but too dark 2814 PRECAPTURE | Sequence done. android.control.aeLock is OFF | CONVERGED | Ready for high-quality capture 2815 PRECAPTURE | Sequence done. android.control.aeLock is ON | LOCKED | Ready for high-quality capture 2816 LOCKED | aeLock is ON and aePrecaptureTrigger is START | LOCKED | Precapture trigger is ignored when AE is already locked 2817 LOCKED | aeLock is ON and aePrecaptureTrigger is CANCEL| LOCKED | Precapture trigger is ignored when AE is already locked 2818 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is START | PRECAPTURE | Start AE precapture metering sequence 2819 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is CANCEL| INACTIVE | Currently active precapture metering sequence is canceled 2820 2821 If the camera device supports AE external flash mode (ON_EXTERNAL_FLASH is included in 2822 android.control.aeAvailableModes), android.control.aeState must be FLASH_REQUIRED after 2823 the camera device finishes AE scan and it's too dark without flash. 2824 2825 For the above table, the camera device may skip reporting any state changes that happen 2826 without application intervention (i.e. mode switch, trigger, locking). Any state that 2827 can be skipped in that manner is called a transient state. 2828 2829 For example, for above AE modes (AE_MODE_ON*), in addition to the state transitions 2830 listed in above table, it is also legal for the camera device to skip one or more 2831 transient states between two results. See below table for examples: 2832 2833 State | Transition Cause | New State | Notes 2834 :-------------:|:-----------------------------------------------------------:|:--------------:|:-----------------: 2835 INACTIVE | Camera device finished AE scan | CONVERGED | Values are already good, transient states are skipped by camera device. 2836 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. 2837 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is START, sequence done | CONVERGED | Converged after a precapture sequence, transient states are skipped by camera device. 2838 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. 2839 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is CANCEL, converged | CONVERGED | Converged after a precapture sequences canceled, transient states are skipped by camera device. 2840 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. 2841 FLASH_REQUIRED | Camera device finished AE scan | CONVERGED | Converged after a new scan, transient states are skipped by camera device. 2842 </details> 2843 </entry> 2844 <clone entry="android.control.afMode" kind="controls"> 2845 </clone> 2846 <clone entry="android.control.afRegions" kind="controls"> 2847 </clone> 2848 <clone entry="android.control.afTrigger" kind="controls"> 2849 </clone> 2850 <entry name="afState" type="byte" visibility="public" enum="true" 2851 hwlevel="legacy"> 2852 <enum> 2853 <value>INACTIVE 2854 <notes>AF is off or has not yet tried to scan/been asked 2855 to scan. 2856 2857 When a camera device is opened, it starts in this 2858 state. This is a transient state, the camera device may 2859 skip reporting this state in capture 2860 result.</notes></value> 2861 <value>PASSIVE_SCAN 2862 <notes>AF is currently performing an AF scan initiated the 2863 camera device in a continuous autofocus mode. 2864 2865 Only used by CONTINUOUS_* AF modes. This is a transient 2866 state, the camera device may skip reporting this state in 2867 capture result.</notes></value> 2868 <value>PASSIVE_FOCUSED 2869 <notes>AF currently believes it is in focus, but may 2870 restart scanning at any time. 2871 2872 Only used by CONTINUOUS_* AF modes. This is a transient 2873 state, the camera device may skip reporting this state in 2874 capture result.</notes></value> 2875 <value>ACTIVE_SCAN 2876 <notes>AF is performing an AF scan because it was 2877 triggered by AF trigger. 2878 2879 Only used by AUTO or MACRO AF modes. This is a transient 2880 state, the camera device may skip reporting this state in 2881 capture result.</notes></value> 2882 <value>FOCUSED_LOCKED 2883 <notes>AF believes it is focused correctly and has locked 2884 focus. 2885 2886 This state is reached only after an explicit START AF trigger has been 2887 sent (android.control.afTrigger), when good focus has been obtained. 2888 2889 The lens will remain stationary until the AF mode (android.control.afMode) is changed or 2890 a new AF trigger is sent to the camera device (android.control.afTrigger). 2891 </notes></value> 2892 <value>NOT_FOCUSED_LOCKED 2893 <notes>AF has failed to focus successfully and has locked 2894 focus. 2895 2896 This state is reached only after an explicit START AF trigger has been 2897 sent (android.control.afTrigger), when good focus cannot be obtained. 2898 2899 The lens will remain stationary until the AF mode (android.control.afMode) is changed or 2900 a new AF trigger is sent to the camera device (android.control.afTrigger). 2901 </notes></value> 2902 <value>PASSIVE_UNFOCUSED 2903 <notes>AF finished a passive scan without finding focus, 2904 and may restart scanning at any time. 2905 2906 Only used by CONTINUOUS_* AF modes. This is a transient state, the camera 2907 device may skip reporting this state in capture result. 2908 2909 LEGACY camera devices do not support this state. When a passive 2910 scan has finished, it will always go to PASSIVE_FOCUSED. 2911 </notes></value> 2912 </enum> 2913 <description>Current state of auto-focus (AF) algorithm.</description> 2914 <details> 2915 Switching between or enabling AF modes (android.control.afMode) always 2916 resets the AF state to INACTIVE. Similarly, switching between android.control.mode, 2917 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2918 the algorithm states to INACTIVE. 2919 2920 The camera device can do several state transitions between two results, if it is 2921 allowed by the state transition table. For example: INACTIVE may never actually be 2922 seen in a result. 2923 2924 The state in the result is the state for this image (in sync with this image): if 2925 AF state becomes FOCUSED, then the image data associated with this result should 2926 be sharp. 2927 2928 Below are state transition tables for different AF modes. 2929 2930 When android.control.afMode is AF_MODE_OFF or AF_MODE_EDOF: 2931 2932 State | Transition Cause | New State | Notes 2933 :------------:|:----------------:|:---------:|:-----------: 2934 INACTIVE | | INACTIVE | Never changes 2935 2936 When android.control.afMode is AF_MODE_AUTO or AF_MODE_MACRO: 2937 2938 State | Transition Cause | New State | Notes 2939 :-----------------:|:----------------:|:------------------:|:--------------: 2940 INACTIVE | AF_TRIGGER | ACTIVE_SCAN | Start AF sweep, Lens now moving 2941 ACTIVE_SCAN | AF sweep done | FOCUSED_LOCKED | Focused, Lens now locked 2942 ACTIVE_SCAN | AF sweep done | NOT_FOCUSED_LOCKED | Not focused, Lens now locked 2943 ACTIVE_SCAN | AF_CANCEL | INACTIVE | Cancel/reset AF, Lens now locked 2944 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF 2945 FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving 2946 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF 2947 NOT_FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving 2948 Any state | Mode change | INACTIVE | 2949 2950 For the above table, the camera device may skip reporting any state changes that happen 2951 without application intervention (i.e. mode switch, trigger, locking). Any state that 2952 can be skipped in that manner is called a transient state. 2953 2954 For example, for these AF modes (AF_MODE_AUTO and AF_MODE_MACRO), in addition to the 2955 state transitions listed in above table, it is also legal for the camera device to skip 2956 one or more transient states between two results. See below table for examples: 2957 2958 State | Transition Cause | New State | Notes 2959 :-----------------:|:----------------:|:------------------:|:--------------: 2960 INACTIVE | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. 2961 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | Focus failed after a scan, lens is now locked. 2962 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. 2963 NOT_FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is good after a scan, lens is not locked. 2964 2965 2966 When android.control.afMode is AF_MODE_CONTINUOUS_VIDEO: 2967 2968 State | Transition Cause | New State | Notes 2969 :-----------------:|:-----------------------------------:|:------------------:|:--------------: 2970 INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2971 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked 2972 PASSIVE_SCAN | Camera device completes current scan| PASSIVE_FOCUSED | End AF scan, Lens now locked 2973 PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, Lens now locked 2974 PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Immediate transition, if focus is good. Lens now locked 2975 PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate transition, if focus is bad. Lens now locked 2976 PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens position, Lens now locked 2977 PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2978 PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2979 PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate transition, lens now locked 2980 PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate transition, lens now locked 2981 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect 2982 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2983 NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect 2984 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2985 2986 When android.control.afMode is AF_MODE_CONTINUOUS_PICTURE: 2987 2988 State | Transition Cause | New State | Notes 2989 :-----------------:|:------------------------------------:|:------------------:|:--------------: 2990 INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2991 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked 2992 PASSIVE_SCAN | Camera device completes current scan | PASSIVE_FOCUSED | End AF scan, Lens now locked 2993 PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, Lens now locked 2994 PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Eventual transition once the focus is good. Lens now locked 2995 PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Eventual transition if cannot find focus. Lens now locked 2996 PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens position, Lens now locked 2997 PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2998 PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2999 PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. Lens now locked 3000 PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. Lens now locked 3001 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect 3002 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 3003 NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect 3004 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 3005 3006 When switch between AF_MODE_CONTINUOUS_* (CAF modes) and AF_MODE_AUTO/AF_MODE_MACRO 3007 (AUTO modes), the initial INACTIVE or PASSIVE_SCAN states may be skipped by the 3008 camera device. When a trigger is included in a mode switch request, the trigger 3009 will be evaluated in the context of the new mode in the request. 3010 See below table for examples: 3011 3012 State | Transition Cause | New State | Notes 3013 :-----------:|:--------------------------------------:|:----------------------------------------:|:--------------: 3014 any state | CAF-->AUTO mode switch | INACTIVE | Mode switch without trigger, initial state must be INACTIVE 3015 any state | CAF-->AUTO mode switch with AF_TRIGGER | trigger-reachable states from INACTIVE | Mode switch with trigger, INACTIVE is skipped 3016 any state | AUTO-->CAF mode switch | passively reachable states from INACTIVE | Mode switch without trigger, passive transient state is skipped 3017 </details> 3018 </entry> 3019 <entry name="afTriggerId" type="int32" visibility="system" deprecated="true"> 3020 <description>The ID sent with the latest 3021 CAMERA2_TRIGGER_AUTOFOCUS call</description> 3022 <deprecation_description> 3023 Removed in camera HAL v3 3024 </deprecation_description> 3025 <details>Must be 0 if no CAMERA2_TRIGGER_AUTOFOCUS trigger 3026 received yet by HAL. Always updated even if AF algorithm 3027 ignores the trigger</details> 3028 </entry> 3029 <clone entry="android.control.awbLock" kind="controls"> 3030 </clone> 3031 <clone entry="android.control.awbMode" kind="controls"> 3032 </clone> 3033 <clone entry="android.control.awbRegions" kind="controls"> 3034 </clone> 3035 <clone entry="android.control.captureIntent" kind="controls"> 3036 </clone> 3037 <entry name="awbState" type="byte" visibility="public" enum="true" 3038 hwlevel="limited"> 3039 <enum> 3040 <value>INACTIVE 3041 <notes>AWB is not in auto mode, or has not yet started metering. 3042 3043 When a camera device is opened, it starts in this 3044 state. This is a transient state, the camera device may 3045 skip reporting this state in capture 3046 result.</notes></value> 3047 <value>SEARCHING 3048 <notes>AWB doesn't yet have a good set of control 3049 values for the current scene. 3050 3051 This is a transient state, the camera device 3052 may skip reporting this state in capture result.</notes></value> 3053 <value>CONVERGED 3054 <notes>AWB has a good set of control values for the 3055 current scene.</notes></value> 3056 <value>LOCKED 3057 <notes>AWB has been locked. 3058 </notes></value> 3059 </enum> 3060 <description>Current state of auto-white balance (AWB) algorithm.</description> 3061 <details>Switching between or enabling AWB modes (android.control.awbMode) always 3062 resets the AWB state to INACTIVE. Similarly, switching between android.control.mode, 3063 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 3064 the algorithm states to INACTIVE. 3065 3066 The camera device can do several state transitions between two results, if it is 3067 allowed by the state transition table. So INACTIVE may never actually be seen in 3068 a result. 3069 3070 The state in the result is the state for this image (in sync with this image): if 3071 AWB state becomes CONVERGED, then the image data associated with this result should 3072 be good to use. 3073 3074 Below are state transition tables for different AWB modes. 3075 3076 When `android.control.awbMode != AWB_MODE_AUTO`: 3077 3078 State | Transition Cause | New State | Notes 3079 :------------:|:----------------:|:---------:|:-----------------------: 3080 INACTIVE | |INACTIVE |Camera device auto white balance algorithm is disabled 3081 3082 When android.control.awbMode is AWB_MODE_AUTO: 3083 3084 State | Transition Cause | New State | Notes 3085 :-------------:|:--------------------------------:|:-------------:|:-----------------: 3086 INACTIVE | Camera device initiates AWB scan | SEARCHING | Values changing 3087 INACTIVE | android.control.awbLock is ON | LOCKED | Values locked 3088 SEARCHING | Camera device finishes AWB scan | CONVERGED | Good values, not changing 3089 SEARCHING | android.control.awbLock is ON | LOCKED | Values locked 3090 CONVERGED | Camera device initiates AWB scan | SEARCHING | Values changing 3091 CONVERGED | android.control.awbLock is ON | LOCKED | Values locked 3092 LOCKED | android.control.awbLock is OFF | SEARCHING | Values not good after unlock 3093 3094 For the above table, the camera device may skip reporting any state changes that happen 3095 without application intervention (i.e. mode switch, trigger, locking). Any state that 3096 can be skipped in that manner is called a transient state. 3097 3098 For example, for this AWB mode (AWB_MODE_AUTO), in addition to the state transitions 3099 listed in above table, it is also legal for the camera device to skip one or more 3100 transient states between two results. See below table for examples: 3101 3102 State | Transition Cause | New State | Notes 3103 :-------------:|:--------------------------------:|:-------------:|:-----------------: 3104 INACTIVE | Camera device finished AWB scan | CONVERGED | Values are already good, transient states are skipped by camera device. 3105 LOCKED | android.control.awbLock is OFF | CONVERGED | Values good after unlock, transient states are skipped by camera device. 3106 </details> 3107 </entry> 3108 <clone entry="android.control.effectMode" kind="controls"> 3109 </clone> 3110 <clone entry="android.control.mode" kind="controls"> 3111 </clone> 3112 <clone entry="android.control.sceneMode" kind="controls"> 3113 </clone> 3114 <clone entry="android.control.videoStabilizationMode" kind="controls"> 3115 </clone> 3116 </dynamic> 3117 <static> 3118 <entry name="availableHighSpeedVideoConfigurations" type="int32" visibility="hidden" 3119 container="array" typedef="highSpeedVideoConfiguration" hwlevel="limited"> 3120 <array> 3121 <size>5</size> 3122 <size>n</size> 3123 </array> 3124 <description> 3125 List of available high speed video size, fps range and max batch size configurations 3126 supported by the camera device, in the format of (width, height, fps_min, fps_max, batch_size_max). 3127 </description> 3128 <range> 3129 For each configuration, the fps_max &gt;= 120fps. 3130 </range> 3131 <details> 3132 When CONSTRAINED_HIGH_SPEED_VIDEO is supported in android.request.availableCapabilities, 3133 this metadata will list the supported high speed video size, fps range and max batch size 3134 configurations. All the sizes listed in this configuration will be a subset of the sizes 3135 reported by {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} 3136 for processed non-stalling formats. 3137 3138 For the high speed video use case, the application must 3139 select the video size and fps range from this metadata to configure the recording and 3140 preview streams and setup the recording requests. For example, if the application intends 3141 to do high speed recording, it can select the maximum size reported by this metadata to 3142 configure output streams. Once the size is selected, application can filter this metadata 3143 by selected size and get the supported fps ranges, and use these fps ranges to setup the 3144 recording requests. Note that for the use case of multiple output streams, application 3145 must select one unique size from this metadata to use (e.g., preview and recording streams 3146 must have the same size). Otherwise, the high speed capture session creation will fail. 3147 3148 The min and max fps will be multiple times of 30fps. 3149 3150 High speed video streaming extends significant performance pressure to camera hardware, 3151 to achieve efficient high speed streaming, the camera device may have to aggregate 3152 multiple frames together and send to camera device for processing where the request 3153 controls are same for all the frames in this batch. Max batch size indicates 3154 the max possible number of frames the camera device will group together for this high 3155 speed stream configuration. This max batch size will be used to generate a high speed 3156 recording request list by 3157 {@link android.hardware.camera2.CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList}. 3158 The max batch size for each configuration will satisfy below conditions: 3159 3160 * Each max batch size will be a divisor of its corresponding fps_max / 30. For example, 3161 if max_fps is 300, max batch size will only be 1, 2, 5, or 10. 3162 * The camera device may choose smaller internal batch size for each configuration, but 3163 the actual batch size will be a divisor of max batch size. For example, if the max batch 3164 size is 8, the actual batch size used by camera device will only be 1, 2, 4, or 8. 3165 * The max batch size in each configuration entry must be no larger than 32. 3166 3167 The camera device doesn't have to support batch mode to achieve high speed video recording, 3168 in such case, batch_size_max will be reported as 1 in each configuration entry. 3169 3170 This fps ranges in this configuration list can only be used to create requests 3171 that are submitted to a high speed camera capture session created by 3172 {@link android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}. 3173 The fps ranges reported in this metadata must not be used to setup capture requests for 3174 normal capture session, or it will cause request error. 3175 </details> 3176 <hal_details> 3177 All the sizes listed in this configuration will be a subset of the sizes reported by 3178 android.scaler.availableStreamConfigurations for processed non-stalling output formats. 3179 Note that for all high speed video configurations, HAL must be able to support a minimum 3180 of two streams, though the application might choose to configure just one stream. 3181 3182 The HAL may support multiple sensor modes for high speed outputs, for example, 120fps 3183 sensor mode and 120fps recording, 240fps sensor mode for 240fps recording. The application 3184 usually starts preview first, then starts recording. To avoid sensor mode switch caused 3185 stutter when starting recording as much as possible, the application may want to ensure 3186 the same sensor mode is used for preview and recording. Therefore, The HAL must advertise 3187 the variable fps range [30, fps_max] for each fixed fps range in this configuration list. 3188 For example, if the HAL advertises [120, 120] and [240, 240], the HAL must also advertise 3189 [30, 120] and [30, 240] for each configuration. In doing so, if the application intends to 3190 do 120fps recording, it can select [30, 120] to start preview, and [120, 120] to start 3191 recording. For these variable fps ranges, it's up to the HAL to decide the actual fps 3192 values that are suitable for smooth preview streaming. 3193 If the HAL sees different max_fps values that fall into different sensor modes in a 3194 sequence of requests, the HAL must switch the sensor mode as quick as possible to minimize 3195 the mode switch caused stutter. 3196 3197 HAL can also support 60fps preview during high speed recording session by advertising 3198 [60, max_fps] for preview and [max_fps, max_fps] for recording. However, HAL must not 3199 advertise both 30fps preview and 60fps preview for the same recording frame rate. 3200 3201 Starting from AIDL ICameraDevice V2, camera HAL must report the valid batch_size_max. The 3202 field will actually be used to generate a high speed recording request list. 3203 </hal_details> 3204 <tag id="V1" /> 3205 </entry> 3206 <entry name="aeLockAvailable" type="byte" visibility="public" enum="true" 3207 typedef="boolean" hwlevel="legacy"> 3208 <enum> 3209 <value>FALSE</value> 3210 <value>TRUE</value> 3211 </enum> 3212 <description>Whether the camera device supports android.control.aeLock</description> 3213 <details> 3214 Devices with MANUAL_SENSOR capability or BURST_CAPTURE capability will always 3215 list `true`. This includes FULL devices. 3216 </details> 3217 <tag id="BC"/> 3218 </entry> 3219 <entry name="awbLockAvailable" type="byte" visibility="public" enum="true" 3220 typedef="boolean" hwlevel="legacy"> 3221 <enum> 3222 <value>FALSE</value> 3223 <value>TRUE</value> 3224 </enum> 3225 <description>Whether the camera device supports android.control.awbLock</description> 3226 <details> 3227 Devices with MANUAL_POST_PROCESSING capability or BURST_CAPTURE capability will 3228 always list `true`. This includes FULL devices. 3229 </details> 3230 <tag id="BC"/> 3231 </entry> 3232 <entry name="availableModes" type="byte" visibility="public" 3233 type_notes="List of enums (android.control.mode)." container="array" 3234 typedef="enumList" hwlevel="legacy"> 3235 <array> 3236 <size>n</size> 3237 </array> 3238 <description> 3239 List of control modes for android.control.mode that are supported by this camera 3240 device. 3241 </description> 3242 <range>Any value listed in android.control.mode</range> 3243 <details> 3244 This list contains control modes that can be set for the camera device. 3245 LEGACY mode devices will always support AUTO mode. LIMITED and FULL 3246 devices will always support OFF, AUTO modes. 3247 </details> 3248 </entry> 3249 <entry name="postRawSensitivityBoostRange" type="int32" visibility="public" 3250 type_notes="Range of supported post RAW sensitivity boosts" 3251 container="array" typedef="rangeInt"> 3252 <array> 3253 <size>2</size> 3254 </array> 3255 <description>Range of boosts for android.control.postRawSensitivityBoost supported 3256 by this camera device. 3257 </description> 3258 <units>ISO arithmetic units, the same as android.sensor.sensitivity</units> 3259 <details> 3260 Devices support post RAW sensitivity boost will advertise 3261 android.control.postRawSensitivityBoost key for controlling 3262 post RAW sensitivity boost. 3263 3264 This key will be `null` for devices that do not support any RAW format 3265 outputs. For devices that do support RAW format outputs, this key will always 3266 present, and if a device does not support post RAW sensitivity boost, it will 3267 list `(100, 100)` in this key. 3268 </details> 3269 <hal_details> 3270 This key is added in legacy HAL3.4. For legacy HAL3.3 or earlier devices, camera 3271 framework will generate this key as `(100, 100)` if device supports any of RAW output 3272 formats. All legacy HAL3.4 and above devices should list this key if device supports 3273 any of RAW output formats. 3274 </hal_details> 3275 </entry> 3276 </static> 3277 <controls> 3278 <entry name="postRawSensitivityBoost" type="int32" visibility="public"> 3279 <description>The amount of additional sensitivity boost applied to output images 3280 after RAW sensor data is captured. 3281 </description> 3282 <units>ISO arithmetic units, the same as android.sensor.sensitivity</units> 3283 <range>android.control.postRawSensitivityBoostRange</range> 3284 <details> 3285 Some camera devices support additional digital sensitivity boosting in the 3286 camera processing pipeline after sensor RAW image is captured. 3287 Such a boost will be applied to YUV/JPEG format output images but will not 3288 have effect on RAW output formats like RAW_SENSOR, RAW10, RAW12 or RAW_OPAQUE. 3289 3290 This key will be `null` for devices that do not support any RAW format 3291 outputs. For devices that do support RAW format outputs, this key will always 3292 present, and if a device does not support post RAW sensitivity boost, it will 3293 list `100` in this key. 3294 3295 If the camera device cannot apply the exact boost requested, it will reduce the 3296 boost to the nearest supported value. 3297 The final boost value used will be available in the output capture result. 3298 3299 For devices that support post RAW sensitivity boost, the YUV/JPEG output images 3300 of such device will have the total sensitivity of 3301 `android.sensor.sensitivity * android.control.postRawSensitivityBoost / 100` 3302 The sensitivity of RAW format images will always be `android.sensor.sensitivity` 3303 3304 This control is only effective if android.control.aeMode or android.control.mode is set to 3305 OFF; otherwise the auto-exposure algorithm will override this value. 3306 </details> 3307 </entry> 3308 </controls> 3309 <dynamic> 3310 <clone entry="android.control.postRawSensitivityBoost" kind="controls"> 3311 </clone> 3312 </dynamic> 3313 <controls> 3314 <entry name="enableZsl" type="byte" visibility="public" enum="true" typedef="boolean"> 3315 <enum> 3316 <value>FALSE 3317 <notes>Requests with android.control.captureIntent == STILL_CAPTURE must be captured 3318 after previous requests.</notes></value> 3319 <value>TRUE 3320 <notes>Requests with android.control.captureIntent == STILL_CAPTURE may or may not be 3321 captured before previous requests.</notes></value> 3322 </enum> 3323 <description>Allow camera device to enable zero-shutter-lag mode for requests with 3324 android.control.captureIntent == STILL_CAPTURE. 3325 </description> 3326 <details> 3327 If enableZsl is `true`, the camera device may enable zero-shutter-lag mode for requests with 3328 STILL_CAPTURE capture intent. The camera device may use images captured in the past to 3329 produce output images for a zero-shutter-lag request. The result metadata including the 3330 android.sensor.timestamp reflects the source frames used to produce output images. 3331 Therefore, the contents of the output images and the result metadata may be out of order 3332 compared to previous regular requests. enableZsl does not affect requests with other 3333 capture intents. 3334 3335 For example, when requests are submitted in the following order: 3336 Request A: enableZsl is ON, android.control.captureIntent is PREVIEW 3337 Request B: enableZsl is ON, android.control.captureIntent is STILL_CAPTURE 3338 3339 The output images for request B may have contents captured before the output images for 3340 request A, and the result metadata for request B may be older than the result metadata for 3341 request A. 3342 3343 Note that when enableZsl is `true`, it is not guaranteed to get output images captured in 3344 the past for requests with STILL_CAPTURE capture intent. 3345 3346 For applications targeting SDK versions O and newer, the value of enableZsl in 3347 TEMPLATE_STILL_CAPTURE template may be `true`. The value in other templates is always 3348 `false` if present. 3349 3350 For applications targeting SDK versions older than O, the value of enableZsl in all 3351 capture templates is always `false` if present. 3352 3353 For application-operated ZSL, use CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template. 3354 </details> 3355 <hal_details> 3356 It is valid for HAL to produce regular output images for requests with STILL_CAPTURE 3357 capture intent. 3358 </hal_details> 3359 </entry> 3360 </controls> 3361 <dynamic> 3362 <clone entry="android.control.enableZsl" kind="controls"> 3363 </clone> 3364 <entry name="afSceneChange" type="byte" visibility="public" enum="true" hal_version="3.3"> 3365 <enum> 3366 <value>NOT_DETECTED 3367 <notes>Scene change is not detected within the AF region(s).</notes></value> 3368 <value>DETECTED 3369 <notes>Scene change is detected within the AF region(s).</notes></value> 3370 </enum> 3371 <description>Whether a significant scene change is detected within the currently-set AF 3372 region(s).</description> 3373 <details>When the camera focus routine detects a change in the scene it is looking at, 3374 such as a large shift in camera viewpoint, significant motion in the scene, or a 3375 significant illumination change, this value will be set to DETECTED for a single capture 3376 result. Otherwise the value will be NOT_DETECTED. The threshold for detection is similar 3377 to what would trigger a new passive focus scan to begin in CONTINUOUS autofocus modes. 3378 3379 This key will be available if the camera device advertises this key via {@link 3380 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 3381 </details> 3382 </entry> 3383 </dynamic> 3384 <static> 3385 <entry name="availableExtendedSceneModeMaxSizes" type="int32" 3386 visibility="ndk_public" optional="true" 3387 type_notes="List of extended scene modes and the corresponding max streaming sizes." 3388 container="array" hwlevel="limited" hal_version="3.5"> 3389 <array> 3390 <size>3</size> 3391 <size>n</size> 3392 </array> 3393 <description> 3394 The list of extended scene modes for android.control.extendedSceneMode that are supported 3395 by this camera device, and each extended scene mode's maximum streaming (non-stall) size 3396 with effect. 3397 </description> 3398 <units>(mode, width, height)</units> 3399 <details> 3400 For DISABLED mode, the camera behaves normally with no extended scene mode enabled. 3401 3402 For BOKEH_STILL_CAPTURE mode, the maximum streaming dimension specifies the limit 3403 under which bokeh is effective when capture intent is PREVIEW. Note that when capture 3404 intent is PREVIEW, the bokeh effect may not be as high in quality compared to 3405 STILL_CAPTURE intent in order to maintain reasonable frame rate. The maximum streaming 3406 dimension must be one of the YUV_420_888 or PRIVATE resolutions in 3407 availableStreamConfigurations, or (0, 0) if preview bokeh is not supported. If the 3408 application configures a stream larger than the maximum streaming dimension, bokeh 3409 effect may not be applied for this stream for PREVIEW intent. 3410 3411 For BOKEH_CONTINUOUS mode, the maximum streaming dimension specifies the limit under 3412 which bokeh is effective. This dimension must be one of the YUV_420_888 or PRIVATE 3413 resolutions in availableStreamConfigurations, and if the sensor maximum resolution is 3414 larger than or equal to 1080p, the maximum streaming dimension must be at least 1080p. 3415 If the application configures a stream with larger dimension, the stream may not have 3416 bokeh effect applied. 3417 </details> 3418 <hal_details> 3419 For available extended scene modes, DISABLED will always be listed. 3420 3421 HAL must support at list one non-OFF extended scene mode if extendedSceneMode control is 3422 available on the camera device. For DISABLED mode, the maximum streaming resolution must 3423 be set to (0, 0). 3424 </hal_details> 3425 </entry> 3426 <entry name="availableExtendedSceneModeZoomRatioRanges" type="float" 3427 visibility="ndk_public" optional="true" 3428 type_notes="Zoom ranges for all supported non-OFF extended scene modes." 3429 container="array" hwlevel="limited" hal_version="3.5"> 3430 <array> 3431 <size>2</size> 3432 <size>n</size> 3433 </array> 3434 <description> 3435 The ranges of supported zoom ratio for non-DISABLED android.control.extendedSceneMode. 3436 </description> 3437 <units>(minZoom, maxZoom)</units> 3438 <details> 3439 When extended scene mode is set, the camera device may have limited range of zoom ratios 3440 compared to when extended scene mode is DISABLED. This tag lists the zoom ratio ranges 3441 for all supported non-DISABLED extended scene modes, in the same order as in 3442 android.control.availableExtended. 3443 3444 Range [1.0, 1.0] means that no zoom (optical or digital) is supported. 3445 </details> 3446 </entry> 3447 <entry name="availableExtendedSceneModeCapabilities" type="int32" visibility="public" 3448 synthetic="true" container="array" typedef="capability" hal_version="3.5"> 3449 <array> 3450 <size>n</size> 3451 </array> 3452 <description>The list of extended scene modes for android.control.extendedSceneMode that 3453 are supported by this camera device, and each extended scene mode's capabilities such 3454 as maximum streaming size, and supported zoom ratio ranges.</description> 3455 <details> 3456 For DISABLED mode, the camera behaves normally with no extended scene mode enabled. 3457 3458 For BOKEH_STILL_CAPTURE mode, the maximum streaming dimension specifies the limit 3459 under which bokeh is effective when capture intent is PREVIEW. Note that when capture 3460 intent is PREVIEW, the bokeh effect may not be as high quality compared to STILL_CAPTURE 3461 intent in order to maintain reasonable frame rate. The maximum streaming dimension must 3462 be one of the YUV_420_888 or PRIVATE resolutions in availableStreamConfigurations, or 3463 (0, 0) if preview bokeh is not supported. If the application configures a stream 3464 larger than the maximum streaming dimension, bokeh effect may not be applied for this 3465 stream for PREVIEW intent. 3466 3467 For BOKEH_CONTINUOUS mode, the maximum streaming dimension specifies the limit under 3468 which bokeh is effective. This dimension must be one of the YUV_420_888 or PRIVATE 3469 resolutions in availableStreamConfigurations, and if the sensor maximum resolution is 3470 larger than or equal to 1080p, the maximum streaming dimension must be at least 1080p. 3471 If the application configures a stream with larger dimension, the stream may not have 3472 bokeh effect applied. 3473 3474 When extended scene mode is set, the camera device may have limited range of zoom ratios 3475 compared to when the mode is DISABLED. availableExtendedSceneModeCapabilities lists the 3476 zoom ranges for all supported extended modes. A range of (1.0, 1.0) means that no zoom 3477 (optical or digital) is supported. 3478 </details> 3479 </entry> 3480 </static> 3481 <controls> 3482 <entry name="extendedSceneMode" type="byte" visibility="public" optional="true" 3483 enum="true" hal_version="3.5"> 3484 <enum> 3485 <value id="0">DISABLED 3486 <notes>Extended scene mode is disabled.</notes></value> 3487 <value>BOKEH_STILL_CAPTURE 3488 <notes>High quality bokeh mode is enabled for all non-raw streams (including YUV, 3489 JPEG, and IMPLEMENTATION_DEFINED) when capture intent is STILL_CAPTURE. Due to the 3490 extra image processing, this mode may introduce additional stall to non-raw streams. 3491 This mode should be used in high quality still capture use case. 3492 </notes> 3493 </value> 3494 <value>BOKEH_CONTINUOUS 3495 <notes>Bokeh effect must not slow down capture rate relative to sensor raw output, 3496 and the effect is applied to all processed streams no larger than the maximum 3497 streaming dimension. This mode should be used if performance and power are a 3498 priority, such as video recording. 3499 </notes> 3500 </value> 3501 <value visibility="hidden" id="0x40">VENDOR_START 3502 <notes> 3503 Vendor defined extended scene modes. These depend on vendor implementation. 3504 </notes> 3505 </value> 3506 </enum> 3507 <description>Whether extended scene mode is enabled for a particular capture request. 3508 </description> 3509 <details> 3510 With bokeh mode, the camera device may blur out the parts of scene that are not in 3511 focus, creating a bokeh (or shallow depth of field) effect for people or objects. 3512 3513 When set to BOKEH_STILL_CAPTURE mode with STILL_CAPTURE capture intent, due to the extra 3514 processing needed for high quality bokeh effect, the stall may be longer than when 3515 capture intent is not STILL_CAPTURE. 3516 3517 When set to BOKEH_STILL_CAPTURE mode with PREVIEW capture intent, 3518 3519 * If the camera device has BURST_CAPTURE capability, the frame rate requirement of 3520 BURST_CAPTURE must still be met. 3521 * All streams not larger than the maximum streaming dimension for BOKEH_STILL_CAPTURE mode 3522 (queried via {@link android.hardware.camera2.CameraCharacteristics#CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_CAPABILITIES|ACAMERA_CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_MAX_SIZES}) 3523 will have preview bokeh effect applied. 3524 3525 When set to BOKEH_CONTINUOUS mode, configured streams dimension should not exceed this mode's 3526 maximum streaming dimension in order to have bokeh effect applied. Bokeh effect may not 3527 be available for streams larger than the maximum streaming dimension. 3528 3529 Switching between different extended scene modes may involve reconfiguration of the camera 3530 pipeline, resulting in long latency. The application should check this key against the 3531 available session keys queried via 3532 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys|ACameraManager_getCameraCharacteristics}. 3533 3534 For a logical multi-camera, bokeh may be implemented by stereo vision from sub-cameras 3535 with different field of view. As a result, when bokeh mode is enabled, the camera device 3536 may override android.scaler.cropRegion or android.control.zoomRatio, and the field of 3537 view may be smaller than when bokeh mode is off. 3538 </details> 3539 </entry> 3540 </controls> 3541 <dynamic> 3542 <clone entry="android.control.extendedSceneMode" kind="controls"> 3543 </clone> 3544 </dynamic> 3545 <static> 3546 <entry name="zoomRatioRange" type="float" visibility="public" 3547 type_notes="The range of zoom ratios that this camera device supports." 3548 container="array" typedef="rangeFloat" hwlevel="limited" hal_version="3.5" 3549 session_characteristics_key_since="35"> 3550 <array> 3551 <size>2</size> 3552 </array> 3553 <description> 3554 Minimum and maximum zoom ratios supported by this camera device. 3555 </description> 3556 <units>A pair of zoom ratio in floating-points: (minZoom, maxZoom)</units> 3557 <range> 3558 maxZoom >= 1.0 >= minZoom 3559 </range> 3560 <details> 3561 If the camera device supports zoom-out from 1x zoom, minZoom will be less than 1.0, and 3562 setting android.control.zoomRatio to values less than 1.0 increases the camera's field 3563 of view. 3564 </details> 3565 <hal_details> 3566 When the key is reported, the camera device's android.scaler.availableMaxDigitalZoom 3567 must be less than or equal to maxZoom. The camera framework makes sure to always 3568 control zoom via android.control.zoomRatio. The android.scaler.cropRegion tag is only 3569 used to do horizontal or vertical cropping (but not both) to achieve aspect ratio 3570 different than the camera sensor's native aspect ratio. 3571 3572 For a logical multi-camera device, this key must either be reported for both the logical 3573 camera device and all its physical sub-cameras, or none of them. 3574 3575 When the key is not reported, camera framework derives the application-facing 3576 zoomRatioRange to be (1, android.scaler.availableMaxDigitalZoom). 3577 </hal_details> 3578 </entry> 3579 </static> 3580 <controls> 3581 <entry name="zoomRatio" type="float" visibility="public" hwlevel="limited" 3582 hal_version="3.5"> 3583 <description> 3584 The desired zoom ratio 3585 </description> 3586 <range>android.control.zoomRatioRange</range> 3587 <details> 3588 Instead of using android.scaler.cropRegion for zoom, the application can now choose to 3589 use this tag to specify the desired zoom level. 3590 3591 By using this control, the application gains a simpler way to control zoom, which can 3592 be a combination of optical and digital zoom. For example, a multi-camera system may 3593 contain more than one lens with different focal lengths, and the user can use optical 3594 zoom by switching between lenses. Using zoomRatio has benefits in the scenarios below: 3595 3596 * Zooming in from a wide-angle lens to a telephoto lens: A floating-point ratio provides 3597 better precision compared to an integer value of android.scaler.cropRegion. 3598 * Zooming out from a wide lens to an ultrawide lens: zoomRatio supports zoom-out whereas 3599 android.scaler.cropRegion doesn't. 3600 3601 To illustrate, here are several scenarios of different zoom ratios, crop regions, 3602 and output streams, for a hypothetical camera device with an active array of size 3603 `(2000,1500)`. 3604 3605 * Camera Configuration: 3606 * Active array size: `2000x1500` (3 MP, 4:3 aspect ratio) 3607 * Output stream #1: `640x480` (VGA, 4:3 aspect ratio) 3608 * Output stream #2: `1280x720` (720p, 16:9 aspect ratio) 3609 * Case #1: 4:3 crop region with 2.0x zoom ratio 3610 * Zoomed field of view: 1/4 of original field of view 3611 * Crop region: `Rect(0, 0, 2000, 1500) // (left, top, right, bottom)` (post zoom) 3612 *  3613 * `640x480` stream source area: `(0, 0, 2000, 1500)` (equal to crop region) 3614 * `1280x720` stream source area: `(0, 187, 2000, 1312)` (letterboxed) 3615 * Case #2: 16:9 crop region with 2.0x zoom. 3616 * Zoomed field of view: 1/4 of original field of view 3617 * Crop region: `Rect(0, 187, 2000, 1312)` 3618 *  3619 * `640x480` stream source area: `(250, 187, 1750, 1312)` (pillarboxed) 3620 * `1280x720` stream source area: `(0, 187, 2000, 1312)` (equal to crop region) 3621 * Case #3: 1:1 crop region with 0.5x zoom out to ultrawide lens. 3622 * Zoomed field of view: 4x of original field of view (switched from wide lens to ultrawide lens) 3623 * Crop region: `Rect(250, 0, 1750, 1500)` 3624 *  3625 * `640x480` stream source area: `(250, 187, 1750, 1312)` (letterboxed) 3626 * `1280x720` stream source area: `(250, 328, 1750, 1172)` (letterboxed) 3627 3628 As seen from the graphs above, the coordinate system of cropRegion now changes to the 3629 effective after-zoom field-of-view, and is represented by the rectangle of (0, 0, 3630 activeArrayWith, activeArrayHeight). The same applies to AE/AWB/AF regions, and faces. 3631 This coordinate system change isn't applicable to RAW capture and its related 3632 metadata such as intrinsicCalibration and lensShadingMap. 3633 3634 Using the same hypothetical example above, and assuming output stream #1 (640x480) is 3635 the viewfinder stream, the application can achieve 2.0x zoom in one of two ways: 3636 3637 * zoomRatio = 2.0, scaler.cropRegion = (0, 0, 2000, 1500) 3638 * zoomRatio = 1.0 (default), scaler.cropRegion = (500, 375, 1500, 1125) 3639 3640 If the application intends to set aeRegions to be top-left quarter of the viewfinder 3641 field-of-view, the android.control.aeRegions should be set to (0, 0, 1000, 750) with 3642 zoomRatio set to 2.0. Alternatively, the application can set aeRegions to the equivalent 3643 region of (500, 375, 1000, 750) for zoomRatio of 1.0. If the application doesn't 3644 explicitly set android.control.zoomRatio, its value defaults to 1.0. 3645 3646 One limitation of controlling zoom using zoomRatio is that the android.scaler.cropRegion 3647 must only be used for letterboxing or pillarboxing of the sensor active array, and no 3648 FREEFORM cropping can be used with android.control.zoomRatio other than 1.0. If 3649 android.control.zoomRatio is not 1.0, and android.scaler.cropRegion is set to be 3650 windowboxing, the camera framework will override the android.scaler.cropRegion to be 3651 the active array. 3652 3653 In the capture request, if the application sets android.control.zoomRatio to a 3654 value != 1.0, the android.control.zoomRatio tag in the capture result reflects the 3655 effective zoom ratio achieved by the camera device, and the android.scaler.cropRegion 3656 adjusts for additional crops that are not zoom related. Otherwise, if the application 3657 sets android.control.zoomRatio to 1.0, or does not set it at all, the 3658 android.control.zoomRatio tag in the result metadata will also be 1.0. 3659 3660 When the application requests a physical stream for a logical multi-camera, the 3661 android.control.zoomRatio in the physical camera result metadata will be 1.0, and 3662 the android.scaler.cropRegion tag reflects the amount of zoom and crop done by the 3663 physical camera device. 3664 </details> 3665 <hal_details> 3666 For all capture request templates, this field must be set to 1.0 in order to have 3667 consistent field of views between different modes. 3668 </hal_details> 3669 </entry> 3670 </controls> 3671 <dynamic> 3672 <clone entry="android.control.zoomRatio" kind="controls"> 3673 </clone> 3674 </dynamic> 3675 <static> 3676 <entry name="availableHighSpeedVideoConfigurationsMaximumResolution" type="int32" 3677 visibility="hidden" container="array" typedef="highSpeedVideoConfiguration" 3678 hal_version="3.6"> 3679 <array> 3680 <size>5</size> 3681 <size>n</size> 3682 </array> 3683 <description> 3684 List of available high speed video size, fps range and max batch size configurations 3685 supported by the camera device, in the format of 3686 (width, height, fps_min, fps_max, batch_size_max), 3687 when android.sensor.pixelMode is set to 3688 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 3689 </description> 3690 <range> 3691 For each configuration, the fps_max &gt;= 120fps. 3692 </range> 3693 <details> 3694 Analogous to android.control.availableHighSpeedVideoConfigurations, for configurations 3695 which are applicable when android.sensor.pixelMode is set to 3696 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 3697 </details> 3698 <hal_details> 3699 Refer to hal details for android.control.availableHighSpeedVideoConfigurations. 3700 </hal_details> 3701 <tag id="V1" /> 3702 </entry> 3703 </static> 3704 <controls> 3705 <entry name="afRegionsSet" type="byte" visibility="fwk_only" 3706 enum="true" typedef="boolean"> 3707 <enum> 3708 <value>FALSE 3709 <notes>AF regions (android.control.afRegions) have not been set by the camera client. 3710 </notes> 3711 </value> 3712 <value>TRUE 3713 <notes> 3714 AF regions (android.control.afRegions) have been set by the camera client. 3715 </notes> 3716 </value> 3717 </enum> 3718 <description> 3719 Framework-only private key which informs camera fwk that the AF regions has been set 3720 by the client and those regions need not be corrected when android.sensor.pixelMode is 3721 set to MAXIMUM_RESOLUTION. 3722 </description> 3723 <details> 3724 This must be set to TRUE by the camera2 java fwk when the camera client sets 3725 android.control.afRegions. 3726 </details> 3727 </entry> 3728 <entry name="aeRegionsSet" type="byte" visibility="fwk_only" 3729 enum="true" typedef="boolean"> 3730 <enum> 3731 <value>FALSE 3732 <notes> AE regions (android.control.aeRegions) have not been set by the camera client. 3733 </notes> 3734 </value> 3735 <value>TRUE 3736 <notes> 3737 AE regions (android.control.aeRegions) have been set by the camera client. 3738 </notes> 3739 </value> 3740 </enum> 3741 <description> 3742 Framework-only private key which informs camera fwk that the AE regions has been set 3743 by the client and those regions need not be corrected when android.sensor.pixelMode is 3744 set to MAXIMUM_RESOLUTION. 3745 </description> 3746 <details> 3747 This must be set to TRUE by the camera2 java fwk when the camera client sets 3748 android.control.aeRegions. 3749 </details> 3750 </entry> 3751 <entry name="awbRegionsSet" type="byte" visibility="fwk_only" 3752 enum="true" typedef="boolean"> 3753 <enum> 3754 <value>FALSE 3755 <notes> AWB regions (android.control.awbRegions) have not been set by the camera client. 3756 </notes> 3757 </value> 3758 <value>TRUE 3759 <notes> 3760 AWB regions (android.control.awbRegions) have been set by the camera client. 3761 </notes> 3762 </value> 3763 </enum> 3764 <description> 3765 Framework-only private key which informs camera fwk that the AF regions has been set 3766 by the client and those regions need not be corrected when android.sensor.pixelMode is 3767 set to MAXIMUM_RESOLUTION. 3768 </description> 3769 <details> 3770 This must be set to TRUE by the camera2 java fwk when the camera client sets 3771 android.control.awbRegions. 3772 </details> 3773 </entry> 3774 <entry name="settingsOverride" type="int32" visibility="public" enum="true" 3775 hal_version="3.9"> 3776 <enum> 3777 <value>OFF 3778 <notes> 3779 No keys are applied sooner than the other keys when applying CaptureRequest 3780 settings to the camera device. This is the default value. 3781 </notes> 3782 </value> 3783 <value>ZOOM 3784 <notes> 3785 Zoom related keys are applied sooner than the other keys in the CaptureRequest. The 3786 zoom related keys are: 3787 3788 * android.control.zoomRatio 3789 * android.scaler.cropRegion 3790 * android.control.aeRegions 3791 * android.control.awbRegions 3792 * android.control.afRegions 3793 3794 Even though android.control.aeRegions, android.control.awbRegions, 3795 and android.control.afRegions are not directly zoom related, applications 3796 typically scale these regions together with android.scaler.cropRegion to have a 3797 consistent mapping within the current field of view. In this aspect, they are 3798 related to android.scaler.cropRegion and android.control.zoomRatio. 3799 </notes> 3800 </value> 3801 <value visibility="hidden" id="0x4000">VENDOR_START 3802 <notes> 3803 Vendor defined settingsOverride. These depend on vendor implementation. 3804 </notes> 3805 </value> 3806 </enum> 3807 <description>The desired CaptureRequest settings override with which certain keys are 3808 applied earlier so that they can take effect sooner. 3809 </description> 3810 <range>android.control.availableSettingsOverrides</range> 3811 <details> 3812 There are some CaptureRequest keys which can be applied earlier than others 3813 when controls within a CaptureRequest aren't required to take effect at the same time. 3814 One such example is zoom. Zoom can be applied at a later stage of the camera pipeline. 3815 As soon as the camera device receives the CaptureRequest, it can apply the requested 3816 zoom value onto an earlier request that's already in the pipeline, thus improves zoom 3817 latency. 3818 3819 This key's value in the capture result reflects whether the controls for this capture 3820 are overridden "by" a newer request. This means that if a capture request turns on 3821 settings override, the capture result of an earlier request will contain the key value 3822 of ZOOM. On the other hand, if a capture request has settings override turned on, 3823 but all newer requests have it turned off, the key's value in the capture result will 3824 be OFF because this capture isn't overridden by a newer capture. In the two examples 3825 below, the capture results columns illustrate the settingsOverride values in different 3826 scenarios. 3827 3828 Assuming the zoom settings override can speed up by 1 frame, below example illustrates 3829 the speed-up at the start of capture session: 3830 3831 Camera session created 3832 Request 1 (zoom=1.0x, override=ZOOM) -> 3833 Request 2 (zoom=1.2x, override=ZOOM) -> 3834 Request 3 (zoom=1.4x, override=ZOOM) -> Result 1 (zoom=1.2x, override=ZOOM) 3835 Request 4 (zoom=1.6x, override=ZOOM) -> Result 2 (zoom=1.4x, override=ZOOM) 3836 Request 5 (zoom=1.8x, override=ZOOM) -> Result 3 (zoom=1.6x, override=ZOOM) 3837 -> Result 4 (zoom=1.8x, override=ZOOM) 3838 -> Result 5 (zoom=1.8x, override=OFF) 3839 3840 The application can turn on settings override and use zoom as normal. The example 3841 shows that the later zoom values (1.2x, 1.4x, 1.6x, and 1.8x) overwrite the zoom 3842 values (1.0x, 1.2x, 1.4x, and 1.8x) of earlier requests (#1, #2, #3, and #4). 3843 3844 The application must make sure the settings override doesn't interfere with user 3845 journeys requiring simultaneous application of all controls in CaptureRequest on the 3846 requested output targets. For example, if the application takes a still capture using 3847 CameraCaptureSession#capture, and the repeating request immediately sets a different 3848 zoom value using override, the inflight still capture could have its zoom value 3849 overwritten unexpectedly. 3850 3851 So the application is strongly recommended to turn off settingsOverride when taking 3852 still/burst captures, and turn it back on when there is only repeating viewfinder 3853 request and no inflight still/burst captures. 3854 3855 Below is the example demonstrating the transitions in and out of the 3856 settings override: 3857 3858 Request 1 (zoom=1.0x, override=OFF) 3859 Request 2 (zoom=1.2x, override=OFF) 3860 Request 3 (zoom=1.4x, override=ZOOM) -> Result 1 (zoom=1.0x, override=OFF) 3861 Request 4 (zoom=1.6x, override=ZOOM) -> Result 2 (zoom=1.4x, override=ZOOM) 3862 Request 5 (zoom=1.8x, override=OFF) -> Result 3 (zoom=1.6x, override=ZOOM) 3863 -> Result 4 (zoom=1.6x, override=OFF) 3864 -> Result 5 (zoom=1.8x, override=OFF) 3865 3866 This example shows that: 3867 3868 * The application "ramps in" settings override by setting the control to ZOOM. 3869 In the example, request #3 enables zoom settings override. Because the camera device 3870 can speed up applying zoom by 1 frame, the outputs of request #2 has 1.4x zoom, the 3871 value specified in request #3. 3872 * The application "ramps out" of settings override by setting the control to OFF. In 3873 the example, request #5 changes the override to OFF. Because request #4's zoom 3874 takes effect in result #3, result #4's zoom remains the same until new value takes 3875 effect in result #5. 3876 </details> 3877 <hal_details> 3878 The HAL must set this value to OFF in all of the Capture templates. 3879 3880 Typically the HAL unblocks processCaptureRequest at the same rate as the sensor capture, 3881 and the HAL queues the capture settings in its pipeline when processCaptureRequest 3882 returns. However, when the settings override is enabled, the HAL can optimize the 3883 overridden controls' latency by applying them as soon as processCaptureRequest is 3884 called, rather than when it's unblocked. 3885 3886 For devices launching with API level 35 or newer, to avoid regression on zoom 3887 smoothness, when zoom settings override is on during pinch zoom (zoom value gradually 3888 changes), the zoom effect in the camera output must not become more jittery. More 3889 specifically, the variation of zoom pipeline latency must not increase. The latency 3890 improvement must be at least 1 frame regardless of zoom in or zoom out. 3891 3892 For devices launched before API level 35, if zoom settings override is on, when 3893 zooming in, the HAL must be able to apply the zoom related settings at least 1 3894 frame ahead. 3895 </hal_details> 3896 </entry> 3897 </controls> 3898 <static> 3899 <entry name="availableSettingsOverrides" type="int32" visibility="public" 3900 optional="true" type_notes="list of enums" container="array" typedef="enumList" 3901 hal_version="3.9"> 3902 <array> 3903 <size>n</size> 3904 </array> 3905 <description>List of available settings overrides supported by the camera device that can 3906 be used to speed up certain controls. 3907 </description> 3908 <range>Any value listed in android.control.settingsOverride</range> 3909 <details>When not all controls within a CaptureRequest are required to take effect 3910 at the same time on the outputs, the camera device may apply certain request keys sooner 3911 to improve latency. This list contains such supported settings overrides. Each settings 3912 override corresponds to a set of CaptureRequest keys that can be sped up when applying. 3913 3914 A supported settings override can be passed in via 3915 {@link android.hardware.camera2.CaptureRequest#CONTROL_SETTINGS_OVERRIDE}, and the 3916 CaptureRequest keys corresponding to the override are applied as soon as possible, not 3917 bound by per-frame synchronization. See android.control.settingsOverride for the 3918 CaptureRequest keys for each override. 3919 3920 OFF is always included in this list. 3921 </details> 3922 </entry> 3923 </static> 3924 <dynamic> 3925 <clone entry="android.control.settingsOverride" kind="controls"> 3926 </clone> 3927 <entry name="settingsOverridingFrameNumber" type="int32" visibility="system" 3928 hal_version="3.9"> 3929 <description>The frame number of the newer request overriding this capture. 3930 </description> 3931 <details>Must be equal to the frame number of the result if this capture isn't 3932 overridden by a newer request, i.e. if android.control.settingsOverride is OFF 3933 in the capture result. On the other hand, if the capture is overridden by a newer 3934 request, the value of this tag (unsigned) must be larger than the frame number of 3935 the capture result.</details> 3936 </entry> 3937 </dynamic> 3938 <controls> 3939 <entry name="autoframing" type="byte" visibility="public" 3940 enum="true" hwlevel="limited" hal_version="3.9"> 3941 <enum> 3942 <value>OFF 3943 <notes> 3944 Disable autoframing. 3945 </notes> 3946 </value> 3947 <value>ON 3948 <notes> 3949 Enable autoframing to keep people in the frame's field of view. 3950 </notes> 3951 </value> 3952 <value visibility="hidden">AUTO 3953 <notes> 3954 Automatically select ON or OFF based on the system level preferences. 3955 </notes> 3956 </value> 3957 </enum> 3958 <description> 3959 Automatic crop, pan and zoom to keep objects in the center of the frame. 3960 </description> 3961 <details> 3962 Auto-framing is a special mode provided by the camera device to dynamically crop, zoom 3963 or pan the camera feed to try to ensure that the people in a scene occupy a reasonable 3964 portion of the viewport. It is primarily designed to support video calling in 3965 situations where the user isn't directly in front of the device, especially for 3966 wide-angle cameras. 3967 android.scaler.cropRegion and android.control.zoomRatio in CaptureResult will be used 3968 to denote the coordinates of the auto-framed region. 3969 Zoom and video stabilization controls are disabled when auto-framing is enabled. The 3A 3970 regions must map the screen coordinates into the scaler crop returned from the capture 3971 result instead of using the active array sensor. 3972 </details> 3973 <hal_details> 3974 While auto-framing is ON, the aspect ratio of the auto-framed region must match the 3975 aspect ratio of the configured output stream. 3976 When reporting CaptureResult, SCALER_CROP_REGION might not adequately describe the 3977 actual sensor pixels. In this case, it is acceptable for the returned parameters to only 3978 be an approximation of the image sensor region that is actually used. 3979 When auto-framing is turned off, the transition should be immediate, with no panning or 3980 zooming to transition to the settings requested by the app. When it is turned on, the 3981 transition can be immediate or smooth. 3982 </hal_details> 3983 </entry> 3984 </controls> 3985 <static> 3986 <entry name="autoframingAvailable" type="byte" visibility="public" enum="true" 3987 typedef="boolean" hwlevel="limited" hal_version="3.9"> 3988 <enum> 3989 <value>FALSE</value> 3990 <value>TRUE</value> 3991 </enum> 3992 <description>Whether the camera device supports android.control.autoframing. 3993 </description> 3994 <details> 3995 Will be `false` if auto-framing is not available. 3996 </details> 3997 </entry> 3998 </static> 3999 <dynamic> 4000 <clone entry="android.control.autoframing" kind="controls"> 4001 </clone> 4002 <entry name="autoframingState" type="byte" visibility="public" 4003 enum="true" hwlevel="limited" hal_version="3.9"> 4004 <enum> 4005 <value>INACTIVE 4006 <notes> 4007 Auto-framing is inactive. 4008 </notes> 4009 </value> 4010 <value>FRAMING 4011 <notes> 4012 Auto-framing is in process - either zooming in, zooming out or pan is taking place. 4013 </notes> 4014 </value> 4015 <value>CONVERGED 4016 <notes> 4017 Auto-framing has reached a stable state (frame/fov is not being adjusted). The state 4018 may transition back to FRAMING if the scene changes. 4019 </notes> 4020 </value> 4021 </enum> 4022 <description>Current state of auto-framing. 4023 </description> 4024 <details> 4025 When the camera doesn't have auto-framing available (i.e 4026 `android.control.autoframingAvailable` == false) or it is not enabled (i.e 4027 `android.control.autoframing` == OFF), the state will always be INACTIVE. 4028 Other states indicate the current auto-framing state: 4029 4030 * When `android.control.autoframing` is set to ON, auto-framing will take 4031 place. While the frame is aligning itself to center the object (doing things like 4032 zooming in, zooming out or pan), the state will be FRAMING. 4033 * When field of view is not being adjusted anymore and has reached a stable state, the 4034 state will be CONVERGED. 4035 </details> 4036 </entry> 4037 </dynamic> 4038 <static> 4039 <entry name="lowLightBoostInfoLuminanceRange" type="float" visibility="public" 4040 optional="true" container="array" typedef="rangeFloat" 4041 aconfig_flag="camera_ae_mode_low_light_boost" hal_version="3.10"> 4042 <array> 4043 <size>2</size> 4044 </array> 4045 <description> 4046 The operating luminance range of low light boost measured in lux (lx). 4047 </description> 4048 <range> 4049 The lower bound indicates the lowest scene luminance value the AE mode 4050 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY' can operate within. Scenes of lower luminance 4051 than this may receive less brightening, increased noise, or artifacts. 4052 4053 The upper bound indicates the luminance threshold at the point when the mode is enabled. 4054 For example, 'Range[0.3, 30.0]' defines 0.3 lux being the lowest scene luminance the 4055 mode can reliably support. 30.0 lux represents the threshold when this mode is 4056 activated. Scenes measured at less than or equal to 30 lux will activate low light 4057 boost. 4058 4059 If this key is defined, then the AE mode 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY' will 4060 also be present. 4061 </range> 4062 </entry> 4063 </static> 4064 <dynamic> 4065 <entry name="lowLightBoostState" type="byte" visibility="public" optional="true" enum="true" 4066 aconfig_flag="camera_ae_mode_low_light_boost" hal_version="3.10"> 4067 <enum> 4068 <value>INACTIVE 4069 <notes> 4070 The AE mode 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY' is enabled but not applied. 4071 </notes></value> 4072 <value>ACTIVE 4073 <notes> 4074 The AE mode 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY' is enabled and applied. 4075 </notes></value> 4076 </enum> 4077 <description> 4078 Current state of the low light boost AE mode. 4079 </description> 4080 <details> 4081 When low light boost is enabled by setting the AE mode to 4082 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY', it can dynamically apply a low light 4083 boost when the light level threshold is exceeded. 4084 4085 This state indicates when low light boost is 'ACTIVE' and applied. Similarly, it can 4086 indicate when it is not being applied by returning 'INACTIVE'. 4087 4088 The default value will always be 'INACTIVE'. 4089 </details> 4090 </entry> 4091 </dynamic> 4092 <controls> 4093 <entry name="zoomMethod" type="byte" visibility="fwk_public" enum="true" 4094 hwlevel="limited" aconfig_flag="zoom_method" hal_version="3.11"> 4095 <enum> 4096 <value id="0">AUTO 4097 <notes> 4098 The camera device automatically detects whether the application does zoom with 4099 android.scaler.cropRegion or android.control.zoomRatio, and in turn decides which 4100 metadata tag reflects the effective zoom level. 4101 </notes></value> 4102 <value id="1">ZOOM_RATIO 4103 <notes> 4104 The application intends to control zoom via android.control.zoomRatio, and 4105 the effective zoom level is reflected by android.control.zoomRatio in capture results. 4106 </notes></value> 4107 </enum> 4108 <description> 4109 Whether the application uses android.scaler.cropRegion or android.control.zoomRatio 4110 to control zoom levels. 4111 </description> 4112 <details> 4113 If set to AUTO, the camera device detects which capture request key the application uses 4114 to do zoom, android.scaler.cropRegion or android.control.zoomRatio. If 4115 the application doesn't set android.scaler.zoomRatio or sets it to 1.0 in the capture 4116 request, the effective zoom level is reflected in android.scaler.cropRegion in capture 4117 results. If android.control.zoomRatio is set to values other than 1.0, the effective 4118 zoom level is reflected in android.control.zoomRatio. AUTO is the default value 4119 for this control, and also the behavior of the OS before Android version 4120 {@link android.os.Build.VERSION_CODES#BAKLAVA BAKLAVA}. 4121 4122 If set to ZOOM_RATIO, the application explicitly specifies zoom level be controlled 4123 by android.control.zoomRatio, and the effective zoom level is reflected in 4124 android.control.zoomRatio in capture results. This addresses an ambiguity with AUTO, 4125 with which the camera device cannot know if the application is using cropRegion or 4126 zoomRatio at 1.0x. 4127 </details> 4128 <hal_details> 4129 Do not use this key directly. It's for camera framework usage, 4130 and not for HAL consumption. 4131 </hal_details> 4132 </entry> 4133 </controls> 4134 <dynamic> 4135 <clone entry="android.control.zoomMethod" kind="controls"> 4136 </clone> 4137 </dynamic> 4138 <controls> 4139 <entry name="aePriorityMode" type="byte" visibility="public" 4140 optional="true" enum="true" aconfig_flag="ae_priority" hal_version="3.11"> 4141 <enum> 4142 <value>OFF 4143 <notes> 4144 Disable AE priority mode. This is the default value. 4145 </notes> 4146 </value> 4147 <value>SENSOR_SENSITIVITY_PRIORITY 4148 <notes> 4149 The camera device's auto-exposure routine is active and 4150 prioritizes the application-selected ISO (android.sensor.sensitivity). 4151 4152 The application has control over android.sensor.sensitivity while 4153 the application's values for android.sensor.exposureTime and 4154 android.sensor.frameDuration are ignored. 4155 </notes> 4156 </value> 4157 <value>SENSOR_EXPOSURE_TIME_PRIORITY 4158 <notes> 4159 The camera device's auto-exposure routine is active and 4160 prioritizes the application-selected exposure time 4161 (android.sensor.exposureTime). 4162 4163 The application has control over android.sensor.exposureTime while 4164 the application's values for android.sensor.sensitivity and 4165 android.sensor.frameDuration are ignored. 4166 </notes> 4167 </value> 4168 </enum> 4169 <description> 4170 Turn on AE priority mode. 4171 </description> 4172 <details> 4173 This control is only effective if android.control.mode is 4174 AUTO and android.control.aeMode is set to one of its 4175 ON modes, with the exception of ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY. 4176 4177 When a priority mode is enabled, the camera device's 4178 auto-exposure routine will maintain the application's 4179 selected parameters relevant to the priority mode while overriding 4180 the remaining exposure parameters 4181 (android.sensor.exposureTime, android.sensor.sensitivity, and 4182 android.sensor.frameDuration). For example, if 4183 SENSOR_SENSITIVITY_PRIORITY mode is enabled, the camera device will 4184 maintain the application-selected android.sensor.sensitivity 4185 while adjusting android.sensor.exposureTime 4186 and android.sensor.frameDuration. The overridden fields for a 4187 given capture will be available in its CaptureResult. 4188 </details> 4189 <hal_details> 4190 The total sensitivity applied for SENSOR_SENSITIVITY_PRIORITY should not be 4191 adjusted by any HAL applied android.control.postRawSensitivityBoost. 4192 </hal_details> 4193 </entry> 4194 </controls> 4195 <dynamic> 4196 <clone entry="android.control.aePriorityMode" kind="controls"> 4197 </clone> 4198 </dynamic> 4199 <static> 4200 <entry name="aeAvailablePriorityModes" type="byte" visibility="public" 4201 type_notes="list of enums" container="array" typedef="enumList" 4202 aconfig_flag="ae_priority" hal_version="3.11"> 4203 <array> 4204 <size>n</size> 4205 </array> 4206 <description> 4207 List of auto-exposure priority modes for android.control.aePriorityMode 4208 that are supported by this camera device. 4209 </description> 4210 <range>Any value listed in android.control.aePriorityMode</range> 4211 <details> 4212 This entry lists the valid modes for 4213 android.control.aePriorityMode for this camera device. 4214 If no AE priority modes are available for a device, this will only list OFF. 4215 </details> 4216 </entry> 4217 </static> 4218 </section> 4219 <section name="demosaic"> 4220 <controls> 4221 <entry name="mode" type="byte" enum="true"> 4222 <enum> 4223 <value>FAST 4224 <notes>Minimal or no slowdown of frame rate compared to 4225 Bayer RAW output.</notes></value> 4226 <value>HIGH_QUALITY 4227 <notes>Improved processing quality but the frame rate might be slowed down 4228 relative to raw output.</notes></value> 4229 </enum> 4230 <description>Controls the quality of the demosaicing 4231 processing.</description> 4232 <tag id="FUTURE" /> 4233 </entry> 4234 </controls> 4235 </section> 4236 <section name="edge"> 4237 <controls> 4238 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 4239 <enum> 4240 <value>OFF 4241 <notes>No edge enhancement is applied.</notes></value> 4242 <value>FAST 4243 <notes>Apply edge enhancement at a quality level that does not slow down frame rate 4244 relative to sensor output. It may be the same as OFF if edge enhancement will 4245 slow down frame rate relative to sensor.</notes></value> 4246 <value>HIGH_QUALITY 4247 <notes>Apply high-quality edge enhancement, at a cost of possibly reduced output frame rate. 4248 </notes></value> 4249 <value optional="true">ZERO_SHUTTER_LAG <notes>Edge enhancement is applied at different 4250 levels for different output streams, based on resolution. Streams at maximum recording 4251 resolution (see {@link 4252 android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession}) 4253 or below have edge enhancement applied, while higher-resolution streams have no edge 4254 enhancement applied. The level of edge enhancement for low-resolution streams is tuned 4255 so that frame rate is not impacted, and the quality is equal to or better than FAST 4256 (since it is only applied to lower-resolution outputs, quality may improve from FAST). 4257 4258 This mode is intended to be used by applications operating in a zero-shutter-lag mode 4259 with YUV or PRIVATE reprocessing, where the application continuously captures 4260 high-resolution intermediate buffers into a circular buffer, from which a final image is 4261 produced via reprocessing when a user takes a picture. For such a use case, the 4262 high-resolution buffers must not have edge enhancement applied to maximize efficiency of 4263 preview and to avoid double-applying enhancement when reprocessed, while low-resolution 4264 buffers (used for recording or preview, generally) need edge enhancement applied for 4265 reasonable preview quality. 4266 4267 This mode is guaranteed to be supported by devices that support either the 4268 YUV_REPROCESSING or PRIVATE_REPROCESSING capabilities 4269 (android.request.availableCapabilities lists either of those capabilities) and it will 4270 be the default mode for CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template. 4271 </notes></value> 4272 </enum> 4273 <description>Operation mode for edge 4274 enhancement.</description> 4275 <range>android.edge.availableEdgeModes</range> 4276 <details>Edge enhancement improves sharpness and details in the captured image. OFF means 4277 no enhancement will be applied by the camera device. 4278 4279 FAST/HIGH_QUALITY both mean camera device determined enhancement 4280 will be applied. HIGH_QUALITY mode indicates that the 4281 camera device will use the highest-quality enhancement algorithms, 4282 even if it slows down capture rate. FAST means the camera device will 4283 not slow down capture rate when applying edge enhancement. FAST may be the same as OFF if 4284 edge enhancement will slow down capture rate. Every output stream will have a similar 4285 amount of enhancement applied. 4286 4287 ZERO_SHUTTER_LAG is meant to be used by applications that maintain a continuous circular 4288 buffer of high-resolution images during preview and reprocess image(s) from that buffer 4289 into a final capture when triggered by the user. In this mode, the camera device applies 4290 edge enhancement to low-resolution streams (below maximum recording resolution) to 4291 maximize preview quality, but does not apply edge enhancement to high-resolution streams, 4292 since those will be reprocessed later if necessary. 4293 4294 For YUV_REPROCESSING, these FAST/HIGH_QUALITY modes both mean that the camera 4295 device will apply FAST/HIGH_QUALITY YUV-domain edge enhancement, respectively. 4296 The camera device may adjust its internal edge enhancement parameters for best 4297 image quality based on the android.reprocess.effectiveExposureFactor, if it is set. 4298 </details> 4299 <hal_details> 4300 For YUV_REPROCESSING The HAL can use android.reprocess.effectiveExposureFactor to 4301 adjust the internal edge enhancement reduction parameters appropriately to get the best 4302 quality images. 4303 </hal_details> 4304 <tag id="V1" /> 4305 <tag id="REPROC" /> 4306 </entry> 4307 <entry name="strength" type="byte"> 4308 <description>Control the amount of edge enhancement 4309 applied to the images</description> 4310 <units>1-10; 10 is maximum sharpening</units> 4311 <tag id="FUTURE" /> 4312 </entry> 4313 </controls> 4314 <static> 4315 <entry name="availableEdgeModes" type="byte" visibility="public" 4316 type_notes="list of enums" container="array" typedef="enumList" 4317 hwlevel="full"> 4318 <array> 4319 <size>n</size> 4320 </array> 4321 <description> 4322 List of edge enhancement modes for android.edge.mode that are supported by this camera 4323 device. 4324 </description> 4325 <range>Any value listed in android.edge.mode</range> 4326 <details> 4327 Full-capability camera devices must always support OFF; camera devices that support 4328 YUV_REPROCESSING or PRIVATE_REPROCESSING will list ZERO_SHUTTER_LAG; all devices will 4329 list FAST. 4330 </details> 4331 <hal_details> 4332 HAL must support both FAST and HIGH_QUALITY if edge enhancement control is available 4333 on the camera device, but the underlying implementation can be the same for both modes. 4334 That is, if the highest quality implementation on the camera device does not slow down 4335 capture rate, then FAST and HIGH_QUALITY will generate the same output. 4336 </hal_details> 4337 <tag id="V1" /> 4338 <tag id="REPROC" /> 4339 </entry> 4340 </static> 4341 <dynamic> 4342 <clone entry="android.edge.mode" kind="controls"> 4343 <tag id="V1" /> 4344 <tag id="REPROC" /> 4345 </clone> 4346 </dynamic> 4347 </section> 4348 <section name="flash"> 4349 <controls> 4350 <entry name="firingPower" type="byte"> 4351 <description>Power for flash firing/torch</description> 4352 <units>10 is max power; 0 is no flash. Linear</units> 4353 <range>0 - 10</range> 4354 <details>Power for snapshot may use a different scale than 4355 for torch mode. Only one entry for torch mode will be 4356 used</details> 4357 <tag id="FUTURE" /> 4358 </entry> 4359 <entry name="firingTime" type="int64"> 4360 <description>Firing time of flash relative to start of 4361 exposure</description> 4362 <units>nanoseconds</units> 4363 <range>0-(exposure time-flash duration)</range> 4364 <details>Clamped to (0, exposure time - flash 4365 duration).</details> 4366 <tag id="FUTURE" /> 4367 </entry> 4368 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 4369 <enum> 4370 <value>OFF 4371 <notes> 4372 Do not fire the flash for this capture. 4373 </notes> 4374 </value> 4375 <value>SINGLE 4376 <notes> 4377 If the flash is available and charged, fire flash 4378 for this capture. 4379 </notes> 4380 </value> 4381 <value>TORCH 4382 <notes> 4383 Transition flash to continuously on. 4384 </notes> 4385 </value> 4386 </enum> 4387 <description>The desired mode for for the camera device's flash control.</description> 4388 <details> 4389 This control is only effective when flash unit is available 4390 (`android.flash.info.available == true`). 4391 4392 When this control is used, the android.control.aeMode must be set to ON or OFF. 4393 Otherwise, the camera device auto-exposure related flash control (ON_AUTO_FLASH, 4394 ON_ALWAYS_FLASH, or ON_AUTO_FLASH_REDEYE) will override this control. 4395 4396 When set to OFF, the camera device will not fire flash for this capture. 4397 4398 When set to SINGLE, the camera device will fire flash regardless of the camera 4399 device's auto-exposure routine's result. When used in still capture case, this 4400 control should be used along with auto-exposure (AE) precapture metering sequence 4401 (android.control.aePrecaptureTrigger), otherwise, the image may be incorrectly exposed. 4402 4403 When set to TORCH, the flash will be on continuously. This mode can be used 4404 for use cases such as preview, auto-focus assist, still capture, or video recording. 4405 4406 The flash status will be reported by android.flash.state in the capture result metadata. 4407 </details> 4408 <tag id="BC" /> 4409 </entry> 4410 </controls> 4411 <static> 4412 <namespace name="info"> 4413 <entry name="available" type="byte" visibility="public" enum="true" 4414 typedef="boolean" hwlevel="legacy"> 4415 <enum> 4416 <value>FALSE</value> 4417 <value>TRUE</value> 4418 </enum> 4419 <description>Whether this camera device has a 4420 flash unit.</description> 4421 <details> 4422 Will be `false` if no flash is available. 4423 4424 If there is no flash unit, none of the flash controls do 4425 anything.</details> 4426 <tag id="BC" /> 4427 </entry> 4428 <entry name="chargeDuration" type="int64"> 4429 <description>Time taken before flash can fire 4430 again</description> 4431 <units>nanoseconds</units> 4432 <range>0-1e9</range> 4433 <details>1 second too long/too short for recharge? Should 4434 this be power-dependent?</details> 4435 <tag id="FUTURE" /> 4436 </entry> 4437 <entry name="strengthMaximumLevel" type="int32" visibility="public" hal_version="3.8"> 4438 <description>Maximum flashlight brightness level. 4439 </description> 4440 <details>If this value is greater than 1, then the device supports controlling the 4441 flashlight brightness level via 4442 {@link android.hardware.camera2.CameraManager#turnOnTorchWithStrengthLevel}. 4443 If this value is equal to 1, flashlight brightness control is not supported. 4444 The value for this key will be null for devices with no flash unit. 4445 4446 The maximum value is guaranteed to be safe to use for an indefinite duration in 4447 terms of device flashlight lifespan, but may be too bright for comfort for many 4448 use cases. Use the default torch brightness value to avoid problems with an 4449 over-bright flashlight. 4450 </details> 4451 </entry> 4452 <entry name="strengthDefaultLevel" type="int32" visibility="public" hal_version="3.8"> 4453 <description>Default flashlight brightness level to be set via 4454 {@link android.hardware.camera2.CameraManager#turnOnTorchWithStrengthLevel}. 4455 </description> 4456 <details> 4457 If flash unit is available this will be greater than or equal to 1 and less 4458 or equal to `android.flash.info.strengthMaximumLevel`. 4459 4460 Setting flashlight brightness above the default level 4461 (i.e.`android.flash.info.strengthDefaultLevel`) may make the device more 4462 likely to reach thermal throttling conditions and slow down, or drain the 4463 battery quicker than normal. To minimize such issues, it is recommended to 4464 start the flashlight at this default brightness until a user explicitly requests 4465 a brighter level. 4466 Note that the value for this key will be null for devices with no flash unit. 4467 The default level should always be > 0. 4468 </details> 4469 </entry> 4470 </namespace> 4471 <entry name="colorTemperature" type="byte"> 4472 <description>The x,y whitepoint of the 4473 flash</description> 4474 <units>pair of floats</units> 4475 <range>0-1 for both</range> 4476 <tag id="FUTURE" /> 4477 </entry> 4478 <entry name="maxEnergy" type="byte"> 4479 <description>Max energy output of the flash for a full 4480 power single flash</description> 4481 <units>lumen-seconds</units> 4482 <range>&gt;= 0</range> 4483 <tag id="FUTURE" /> 4484 </entry> 4485 </static> 4486 <dynamic> 4487 <clone entry="android.flash.firingPower" kind="controls"> 4488 </clone> 4489 <clone entry="android.flash.firingTime" kind="controls"> 4490 </clone> 4491 <clone entry="android.flash.mode" kind="controls"></clone> 4492 <entry name="state" type="byte" visibility="public" enum="true" 4493 hwlevel="limited"> 4494 <enum> 4495 <value>UNAVAILABLE 4496 <notes>No flash on camera.</notes></value> 4497 <value>CHARGING 4498 <notes>Flash is charging and cannot be fired.</notes></value> 4499 <value>READY 4500 <notes>Flash is ready to fire.</notes></value> 4501 <value>FIRED 4502 <notes>Flash fired for this capture.</notes></value> 4503 <value>PARTIAL 4504 <notes>Flash partially illuminated this frame. 4505 4506 This is usually due to the next or previous frame having 4507 the flash fire, and the flash spilling into this capture 4508 due to hardware limitations.</notes></value> 4509 </enum> 4510 <description>Current state of the flash 4511 unit.</description> 4512 <details> 4513 When the camera device doesn't have flash unit 4514 (i.e. `android.flash.info.available == false`), this state will always be UNAVAILABLE. 4515 Other states indicate the current flash status. 4516 4517 In certain conditions, this will be available on LEGACY devices: 4518 4519 * Flash-less cameras always return UNAVAILABLE. 4520 * Using android.control.aeMode `==` ON_ALWAYS_FLASH 4521 will always return FIRED. 4522 * Using android.flash.mode `==` TORCH 4523 will always return FIRED. 4524 4525 In all other conditions the state will not be available on 4526 LEGACY devices (i.e. it will be `null`). 4527 </details> 4528 </entry> 4529 </dynamic> 4530 <controls> 4531 <entry name="strengthLevel" type="int32" visibility="public" hwlevel="legacy" 4532 hal_version="3.10"> 4533 <description>Flash strength level to be used when manual flash control is active. 4534 </description> 4535 <range>`[1-android.flash.torchStrengthMaxLevel]` when the android.flash.mode is 4536 set to TORCH; 4537 `[1-android.flash.singleStrengthMaxLevel]` when the android.flash.mode is 4538 set to SINGLE 4539 </range> 4540 <details>Flash strength level to use in capture mode i.e. when the applications control 4541 flash with either `SINGLE` or `TORCH` mode. 4542 4543 Use android.flash.singleStrengthMaxLevel and 4544 android.flash.torchStrengthMaxLevel to check whether the device supports 4545 flash strength control or not. 4546 If the values of android.flash.singleStrengthMaxLevel and 4547 android.flash.torchStrengthMaxLevel are greater than 1, 4548 then the device supports manual flash strength control. 4549 4550 If the android.flash.mode `==` `TORCH` the value must be &gt;= 1 4551 and &lt;= android.flash.torchStrengthMaxLevel. 4552 If the application doesn't set the key and 4553 android.flash.torchStrengthMaxLevel &gt; 1, 4554 then the flash will be fired at the default level set by HAL in 4555 android.flash.torchStrengthDefaultLevel. 4556 If the android.flash.mode `==` `SINGLE`, then the value must be &gt;= 1 4557 and &lt;= android.flash.singleStrengthMaxLevel. 4558 If the application does not set this key and 4559 android.flash.singleStrengthMaxLevel &gt; 1, 4560 then the flash will be fired at the default level set by HAL 4561 in android.flash.singleStrengthDefaultLevel. 4562 If android.control.aeMode is set to any of `ON_AUTO_FLASH`, `ON_ALWAYS_FLASH`, 4563 `ON_AUTO_FLASH_REDEYE`, `ON_EXTERNAL_FLASH` values, then the strengthLevel will be ignored. 4564 4565 When AE mode is ON and flash mode is TORCH or SINGLE, the application should make sure 4566 the AE mode, flash mode, and flash strength level remain the same between precapture 4567 trigger request and final capture request. The flash strength level being set during 4568 precapture sequence is used by the camera device as a reference. The actual strength 4569 may be less, and the auto-exposure routine makes sure proper conversions of sensor 4570 exposure time and sensitivities between precapture and final capture for the specified 4571 strength level. 4572 </details> 4573 </entry> 4574 </controls> 4575 <static> 4576 <entry name="singleStrengthMaxLevel" type="int32" visibility="public" 4577 hwlevel="legacy" hal_version="3.10"> 4578 <description>Maximum flash brightness level for manual flash control in `SINGLE` mode. 4579 </description> 4580 <details> 4581 Maximum flash brightness level in camera capture mode and 4582 android.flash.mode set to `SINGLE`. 4583 Value will be &gt; 1 if the manual flash strength control feature is supported, 4584 otherwise the value will be equal to 1. 4585 Note that this level is just a number of supported levels (the granularity of control). 4586 There is no actual physical power units tied to this level. 4587 </details> 4588 </entry> 4589 <entry name="singleStrengthDefaultLevel" type="int32" 4590 visibility="public" hwlevel="legacy" hal_version="3.10"> 4591 <description>Default flash brightness level for manual flash control in `SINGLE` mode. 4592 </description> 4593 <details> 4594 If flash unit is available this will be greater than or equal to 1 and less 4595 or equal to android.flash.singleStrengthMaxLevel. 4596 Note for devices that do not support the manual flash strength control 4597 feature, this level will always be equal to 1. 4598 </details> 4599 </entry> 4600 <entry name="torchStrengthMaxLevel" type="int32" visibility="public" 4601 hwlevel="legacy" hal_version="3.10"> 4602 <description>Maximum flash brightness level for manual flash control in `TORCH` mode 4603 </description> 4604 <details> 4605 Maximum flash brightness level in camera capture mode and 4606 android.flash.mode set to `TORCH`. 4607 Value will be &gt; 1 if the manual flash strength control feature is supported, 4608 otherwise the value will be equal to 1. 4609 4610 Note that this level is just a number of supported levels(the granularity of control). 4611 There is no actual physical power units tied to this level. 4612 There is no relation between android.flash.torchStrengthMaxLevel and 4613 android.flash.singleStrengthMaxLevel i.e. the ratio of 4614 android.flash.torchStrengthMaxLevel:android.flash.singleStrengthMaxLevel 4615 is not guaranteed to be the ratio of actual brightness. 4616 </details> 4617 </entry> 4618 <entry name="torchStrengthDefaultLevel" type="int32" visibility="public" 4619 hwlevel="legacy" hal_version="3.10"> 4620 <description>Default flash brightness level for manual flash control in `TORCH` mode 4621 </description> 4622 <details> 4623 If flash unit is available this will be greater than or equal to 1 and less 4624 or equal to android.flash.torchStrengthMaxLevel. 4625 Note for the devices that do not support the manual flash strength control feature, 4626 this level will always be equal to 1. 4627 </details> 4628 </entry> 4629 </static> 4630 <dynamic> 4631 <clone entry="android.flash.strengthLevel" kind="controls"> 4632 </clone> 4633 </dynamic> 4634 </section> 4635 <section name="hotPixel"> 4636 <controls> 4637 <entry name="mode" type="byte" visibility="public" enum="true"> 4638 <enum> 4639 <value>OFF 4640 <notes> 4641 No hot pixel correction is applied. 4642 4643 The frame rate must not be reduced relative to sensor raw output 4644 for this option. 4645 4646 The hotpixel map may be returned in android.statistics.hotPixelMap. 4647 </notes> 4648 </value> 4649 <value>FAST 4650 <notes> 4651 Hot pixel correction is applied, without reducing frame 4652 rate relative to sensor raw output. 4653 4654 The hotpixel map may be returned in android.statistics.hotPixelMap. 4655 </notes> 4656 </value> 4657 <value>HIGH_QUALITY 4658 <notes> 4659 High-quality hot pixel correction is applied, at a cost 4660 of possibly reduced frame rate relative to sensor raw output. 4661 4662 The hotpixel map may be returned in android.statistics.hotPixelMap. 4663 </notes> 4664 </value> 4665 </enum> 4666 <description> 4667 Operational mode for hot pixel correction. 4668 </description> 4669 <range>android.hotPixel.availableHotPixelModes</range> 4670 <details> 4671 Hotpixel correction interpolates out, or otherwise removes, pixels 4672 that do not accurately measure the incoming light (i.e. pixels that 4673 are stuck at an arbitrary value or are oversensitive). 4674 </details> 4675 <tag id="V1" /> 4676 <tag id="RAW" /> 4677 </entry> 4678 </controls> 4679 <static> 4680 <entry name="availableHotPixelModes" type="byte" visibility="public" 4681 type_notes="list of enums" container="array" typedef="enumList"> 4682 <array> 4683 <size>n</size> 4684 </array> 4685 <description> 4686 List of hot pixel correction modes for android.hotPixel.mode that are supported by this 4687 camera device. 4688 </description> 4689 <range>Any value listed in android.hotPixel.mode</range> 4690 <details> 4691 FULL mode camera devices will always support FAST. 4692 </details> 4693 <hal_details> 4694 To avoid performance issues, there will be significantly fewer hot 4695 pixels than actual pixels on the camera sensor. 4696 HAL must support both FAST and HIGH_QUALITY if hot pixel correction control is available 4697 on the camera device, but the underlying implementation can be the same for both modes. 4698 That is, if the highest quality implementation on the camera device does not slow down 4699 capture rate, then FAST and HIGH_QUALITY will generate the same output. 4700 </hal_details> 4701 <tag id="V1" /> 4702 <tag id="RAW" /> 4703 </entry> 4704 </static> 4705 <dynamic> 4706 <clone entry="android.hotPixel.mode" kind="controls"> 4707 <tag id="V1" /> 4708 <tag id="RAW" /> 4709 </clone> 4710 </dynamic> 4711 </section> 4712 <section name="jpeg"> 4713 <controls> 4714 <entry name="gpsLocation" type="byte" visibility="java_public" synthetic="true" 4715 typedef="location" hwlevel="legacy"> 4716 <description> 4717 A location object to use when generating image GPS metadata. 4718 </description> 4719 <details> 4720 Setting a location object in a request will include the GPS coordinates of the location 4721 into any JPEG images captured based on the request. These coordinates can then be 4722 viewed by anyone who receives the JPEG image. 4723 4724 This tag is also used for HEIC image capture. 4725 </details> 4726 </entry> 4727 <entry name="gpsCoordinates" type="double" visibility="ndk_public" 4728 type_notes="latitude, longitude, altitude. First two in degrees, the third in meters" 4729 container="array" hwlevel="legacy"> 4730 <array> 4731 <size>3</size> 4732 </array> 4733 <description>GPS coordinates to include in output JPEG 4734 EXIF.</description> 4735 <range>(-180 - 180], [-90,90], [-inf, inf]</range> 4736 <details>This tag is also used for HEIC image capture.</details> 4737 <tag id="BC" /> 4738 </entry> 4739 <entry name="gpsProcessingMethod" type="byte" visibility="ndk_public" 4740 typedef="string" hwlevel="legacy"> 4741 <description>32 characters describing GPS algorithm to 4742 include in EXIF.</description> 4743 <units>UTF-8 null-terminated string</units> 4744 <details>This tag is also used for HEIC image capture.</details> 4745 <tag id="BC" /> 4746 </entry> 4747 <entry name="gpsTimestamp" type="int64" visibility="ndk_public" hwlevel="legacy"> 4748 <description>Time GPS fix was made to include in 4749 EXIF.</description> 4750 <units>UTC in seconds since January 1, 1970</units> 4751 <details>This tag is also used for HEIC image capture.</details> 4752 <tag id="BC" /> 4753 </entry> 4754 <entry name="orientation" type="int32" visibility="public" hwlevel="legacy"> 4755 <description>The orientation for a JPEG image.</description> 4756 <units>Degrees in multiples of 90</units> 4757 <range>0, 90, 180, 270</range> 4758 <details> 4759 The clockwise rotation angle in degrees, relative to the orientation 4760 to the camera, that the JPEG picture needs to be rotated by, to be viewed 4761 upright. 4762 4763 Camera devices may either encode this value into the JPEG EXIF header, or 4764 rotate the image data to match this orientation. When the image data is rotated, 4765 the thumbnail data will also be rotated. Additionally, in the case where the image data 4766 is rotated, {@link android.media.Image#getWidth} and {@link android.media.Image#getHeight} 4767 will not be updated to reflect the height and width of the rotated image. 4768 4769 Note that this orientation is relative to the orientation of the camera sensor, given 4770 by android.sensor.orientation. 4771 4772 To translate from the device orientation given by the Android sensor APIs for camera 4773 sensors which are not EXTERNAL, the following sample code may be used: 4774 4775 private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) { 4776 if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0; 4777 int sensorOrientation = c.get(CameraCharacteristics.SENSOR_ORIENTATION); 4778 4779 // Round device orientation to a multiple of 90 4780 deviceOrientation = (deviceOrientation + 45) / 90 * 90; 4781 4782 // Reverse device orientation for front-facing cameras 4783 boolean facingFront = c.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_FRONT; 4784 if (facingFront) deviceOrientation = -deviceOrientation; 4785 4786 // Calculate desired JPEG orientation relative to camera orientation to make 4787 // the image upright relative to the device orientation 4788 int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360; 4789 4790 return jpegOrientation; 4791 } 4792 4793 For EXTERNAL cameras the sensor orientation will always be set to 0 and the facing will 4794 also be set to EXTERNAL. The above code is not relevant in such case. 4795 4796 This tag is also used to describe the orientation of the HEIC image capture, in which 4797 case the rotation is reflected by 4798 {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}, and not by 4799 rotating the image data itself. 4800 </details> 4801 <tag id="BC" /> 4802 </entry> 4803 <entry name="quality" type="byte" visibility="public" hwlevel="legacy"> 4804 <description>Compression quality of the final JPEG 4805 image.</description> 4806 <range>1-100; larger is higher quality</range> 4807 <details>85-95 is typical usage range. This tag is also used to describe the quality 4808 of the HEIC image capture.</details> 4809 <tag id="BC" /> 4810 </entry> 4811 <entry name="thumbnailQuality" type="byte" visibility="public" hwlevel="legacy"> 4812 <description>Compression quality of JPEG 4813 thumbnail.</description> 4814 <range>1-100; larger is higher quality</range> 4815 <details>This tag is also used to describe the quality of the HEIC image capture.</details> 4816 <tag id="BC" /> 4817 </entry> 4818 <entry name="thumbnailSize" type="int32" visibility="public" 4819 container="array" typedef="size" hwlevel="legacy"> 4820 <array> 4821 <size>2</size> 4822 </array> 4823 <description>Resolution of embedded JPEG thumbnail.</description> 4824 <range>android.jpeg.availableThumbnailSizes</range> 4825 <details>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, 4826 but the captured JPEG will still be a valid image. 4827 4828 For best results, when issuing a request for a JPEG image, the thumbnail size selected 4829 should have the same aspect ratio as the main JPEG output. 4830 4831 If the thumbnail image aspect ratio differs from the JPEG primary image aspect 4832 ratio, the camera device creates the thumbnail by cropping it from the primary image. 4833 For example, if the primary image has 4:3 aspect ratio, the thumbnail image has 4834 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to 4835 generate the thumbnail image. The thumbnail image will always have a smaller Field 4836 Of View (FOV) than the primary image when aspect ratios differ. 4837 4838 When an android.jpeg.orientation of non-zero degree is requested, 4839 the camera device will handle thumbnail rotation in one of the following ways: 4840 4841 * Set the {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag} 4842 and keep jpeg and thumbnail image data unrotated. 4843 * Rotate the jpeg and thumbnail image data and not set 4844 {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}. In this 4845 case, LIMITED or FULL hardware level devices will report rotated thumbnail size in 4846 capture result, so the width and height will be interchanged if 90 or 270 degree 4847 orientation is requested. LEGACY device will always report unrotated thumbnail 4848 size. 4849 4850 The tag is also used as thumbnail size for HEIC image format capture, in which case the 4851 the thumbnail rotation is reflected by 4852 {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}, and not by 4853 rotating the thumbnail data itself. 4854 </details> 4855 <hal_details> 4856 The HAL must not squeeze or stretch the downscaled primary image to generate thumbnail. 4857 The cropping must be done on the primary jpeg image rather than the sensor pre-correction 4858 active array. The stream cropping rule specified by "S5. Cropping" in camera3.h doesn't 4859 apply to the thumbnail image cropping. 4860 </hal_details> 4861 <tag id="BC" /> 4862 </entry> 4863 </controls> 4864 <static> 4865 <entry name="availableThumbnailSizes" type="int32" visibility="public" 4866 container="array" typedef="size" hwlevel="legacy"> 4867 <array> 4868 <size>2</size> 4869 <size>n</size> 4870 </array> 4871 <description>List of JPEG thumbnail sizes for android.jpeg.thumbnailSize supported by this 4872 camera device.</description> 4873 <details> 4874 This list will include at least one non-zero resolution, plus `(0,0)` for indicating no 4875 thumbnail should be generated. 4876 4877 Below conditions will be satisfied for this size list: 4878 4879 * The sizes will be sorted by increasing pixel area (width x height). 4880 If several resolutions have the same area, they will be sorted by increasing width. 4881 * The aspect ratio of the largest thumbnail size will be same as the 4882 aspect ratio of largest JPEG output size in android.scaler.availableStreamConfigurations. 4883 The largest size is defined as the size that has the largest pixel area 4884 in a given size list. 4885 * Each output JPEG size in android.scaler.availableStreamConfigurations will have at least 4886 one corresponding size that has the same aspect ratio in availableThumbnailSizes, 4887 and vice versa. 4888 * All non-`(0, 0)` sizes will have non-zero widths and heights. 4889 4890 This list is also used as supported thumbnail sizes for HEIC image format capture. 4891 </details> 4892 <tag id="BC" /> 4893 </entry> 4894 <entry name="maxSize" type="int32" visibility="system"> 4895 <description>Maximum size in bytes for the compressed 4896 JPEG buffer, in default sensor pixel mode (see android.sensor.pixelMode)</description> 4897 <range>Must be large enough to fit any JPEG produced by 4898 the camera</range> 4899 <details>This is used for sizing the gralloc buffers for 4900 JPEG</details> 4901 </entry> 4902 </static> 4903 <dynamic> 4904 <clone entry="android.jpeg.gpsLocation" kind="controls"> 4905 </clone> 4906 <clone entry="android.jpeg.gpsCoordinates" kind="controls"> 4907 </clone> 4908 <clone entry="android.jpeg.gpsProcessingMethod" 4909 kind="controls"></clone> 4910 <clone entry="android.jpeg.gpsTimestamp" kind="controls"> 4911 </clone> 4912 <clone entry="android.jpeg.orientation" kind="controls"> 4913 </clone> 4914 <clone entry="android.jpeg.quality" kind="controls"> 4915 </clone> 4916 <entry name="size" type="int32"> 4917 <description>The size of the compressed JPEG image, in 4918 bytes</description> 4919 <range>&gt;= 0</range> 4920 <details>If no JPEG output is produced for the request, 4921 this must be 0. 4922 4923 Otherwise, this describes the real size of the compressed 4924 JPEG image placed in the output stream. More specifically, 4925 if android.jpeg.maxSize = 1000000, and a specific capture 4926 has android.jpeg.size = 500000, then the output buffer from 4927 the JPEG stream will be 1000000 bytes, of which the first 4928 500000 make up the real data.</details> 4929 <tag id="FUTURE" /> 4930 </entry> 4931 <clone entry="android.jpeg.thumbnailQuality" 4932 kind="controls"></clone> 4933 <clone entry="android.jpeg.thumbnailSize" kind="controls"> 4934 </clone> 4935 </dynamic> 4936 </section> 4937 <section name="lens"> 4938 <controls> 4939 <entry name="aperture" type="float" visibility="public" hwlevel="full"> 4940 <description>The desired lens aperture size, as a ratio of lens focal length to the 4941 effective aperture diameter.</description> 4942 <units>The f-number (f/N)</units> 4943 <range>android.lens.info.availableApertures</range> 4944 <details>Setting this value is only supported on the camera devices that have a variable 4945 aperture lens. 4946 4947 When this is supported and android.control.aeMode is OFF, 4948 this can be set along with android.sensor.exposureTime, 4949 android.sensor.sensitivity, and android.sensor.frameDuration 4950 to achieve manual exposure control. 4951 4952 The requested aperture value may take several frames to reach the 4953 requested value; the camera device will report the current (intermediate) 4954 aperture size in capture result metadata while the aperture is changing. 4955 While the aperture is still changing, android.lens.state will be set to MOVING. 4956 4957 When this is supported and android.control.aeMode is one of 4958 the ON modes, this will be overridden by the camera device 4959 auto-exposure algorithm, the overridden values are then provided 4960 back to the user in the corresponding result.</details> 4961 <tag id="V1" /> 4962 </entry> 4963 <entry name="filterDensity" type="float" visibility="public" hwlevel="full"> 4964 <description> 4965 The desired setting for the lens neutral density filter(s). 4966 </description> 4967 <units>Exposure Value (EV)</units> 4968 <range>android.lens.info.availableFilterDensities</range> 4969 <details> 4970 This control will not be supported on most camera devices. 4971 4972 Lens filters are typically used to lower the amount of light the 4973 sensor is exposed to (measured in steps of EV). As used here, an EV 4974 step is the standard logarithmic representation, which are 4975 non-negative, and inversely proportional to the amount of light 4976 hitting the sensor. For example, setting this to 0 would result 4977 in no reduction of the incoming light, and setting this to 2 would 4978 mean that the filter is set to reduce incoming light by two stops 4979 (allowing 1/4 of the prior amount of light to the sensor). 4980 4981 It may take several frames before the lens filter density changes 4982 to the requested value. While the filter density is still changing, 4983 android.lens.state will be set to MOVING. 4984 </details> 4985 <tag id="V1" /> 4986 </entry> 4987 <entry name="focalLength" type="float" visibility="public" hwlevel="legacy"> 4988 <description> 4989 The desired lens focal length; used for optical zoom. 4990 </description> 4991 <units>Millimeters</units> 4992 <range>android.lens.info.availableFocalLengths</range> 4993 <details> 4994 This setting controls the physical focal length of the camera 4995 device's lens. Changing the focal length changes the field of 4996 view of the camera device, and is usually used for optical zoom. 4997 4998 Like android.lens.focusDistance and android.lens.aperture, this 4999 setting won't be applied instantaneously, and it may take several 5000 frames before the lens can change to the requested focal length. 5001 While the focal length is still changing, android.lens.state will 5002 be set to MOVING. 5003 5004 Optical zoom via this control will not be supported on most devices. Starting from API 5005 level 30, the camera device may combine optical and digital zoom through the 5006 android.control.zoomRatio control. 5007 </details> 5008 <hal_details> 5009 For a logical camera device supporting both optical and digital zoom, if focalLength and 5010 cropRegion change in the same request, the camera device must make sure that the new 5011 focalLength and cropRegion take effect in the same frame. This is to make sure that there 5012 is no visible field-of-view jump during zoom. For example, if cropRegion is applied 5013 immediately, but focalLength takes more than 1 frame to take effect, the camera device 5014 will delay the cropRegion so that it's synchronized with focalLength. 5015 5016 Starting from API level 30, it's strongly recommended for HAL to implement the 5017 combination of optical and digital zoom using the new android.control.zoomRatio API, in 5018 lieu of using android.lens.focalLength and android.scaler.cropRegion. 5019 </hal_details> 5020 <tag id="V1" /> 5021 </entry> 5022 <entry name="focusDistance" type="float" visibility="public" hwlevel="full"> 5023 <description>Desired distance to plane of sharpest focus, 5024 measured from frontmost surface of the lens.</description> 5025 <units>See android.lens.info.focusDistanceCalibration for details</units> 5026 <range>&gt;= 0</range> 5027 <details> 5028 This control can be used for setting manual focus, on devices that support 5029 the MANUAL_SENSOR capability and have a variable-focus lens (see 5030 android.lens.info.minimumFocusDistance). 5031 5032 A value of `0.0f` means infinity focus. The value set will be clamped to 5033 `[0.0f, android.lens.info.minimumFocusDistance]`. 5034 5035 Like android.lens.focalLength, this setting won't be applied 5036 instantaneously, and it may take several frames before the lens 5037 can move to the requested focus distance. While the lens is still moving, 5038 android.lens.state will be set to MOVING. 5039 5040 LEGACY devices support at most setting this to `0.0f` 5041 for infinity focus. 5042 </details> 5043 <tag id="BC" /> 5044 <tag id="V1" /> 5045 </entry> 5046 <entry name="opticalStabilizationMode" type="byte" visibility="public" 5047 enum="true" hwlevel="limited"> 5048 <enum> 5049 <value>OFF 5050 <notes>Optical stabilization is unavailable.</notes> 5051 </value> 5052 <value optional="true">ON 5053 <notes>Optical stabilization is enabled.</notes> 5054 </value> 5055 </enum> 5056 <description> 5057 Sets whether the camera device uses optical image stabilization (OIS) 5058 when capturing images. 5059 </description> 5060 <range>android.lens.info.availableOpticalStabilization</range> 5061 <details> 5062 OIS is used to compensate for motion blur due to small 5063 movements of the camera during capture. Unlike digital image 5064 stabilization (android.control.videoStabilizationMode), OIS 5065 makes use of mechanical elements to stabilize the camera 5066 sensor, and thus allows for longer exposure times before 5067 camera shake becomes apparent. 5068 5069 Switching between different optical stabilization modes may take several 5070 frames to initialize, the camera device will report the current mode in 5071 capture result metadata. For example, When "ON" mode is requested, the 5072 optical stabilization modes in the first several capture results may still 5073 be "OFF", and it will become "ON" when the initialization is done. 5074 5075 If a camera device supports both OIS and digital image stabilization 5076 (android.control.videoStabilizationMode), turning both modes on may produce undesirable 5077 interaction, so it is recommended not to enable both at the same time. 5078 5079 If android.control.videoStabilizationMode is set to "PREVIEW_STABILIZATION", 5080 android.lens.opticalStabilizationMode is overridden. The camera sub-system may choose 5081 to turn on hardware based image stabilization in addition to software based stabilization 5082 if it deems that appropriate. This key's value in the capture result will reflect which 5083 OIS mode was chosen. 5084 5085 Not all devices will support OIS; see 5086 android.lens.info.availableOpticalStabilization for 5087 available controls. 5088 </details> 5089 <tag id="V1" /> 5090 </entry> 5091 </controls> 5092 <static> 5093 <namespace name="info"> 5094 <entry name="availableApertures" type="float" visibility="public" 5095 container="array" hwlevel="full"> 5096 <array> 5097 <size>n</size> 5098 </array> 5099 <description>List of aperture size values for android.lens.aperture that are 5100 supported by this camera device.</description> 5101 <units>The aperture f-number</units> 5102 <details>If the camera device doesn't support a variable lens aperture, 5103 this list will contain only one value, which is the fixed aperture size. 5104 5105 If the camera device supports a variable aperture, the aperture values 5106 in this list will be sorted in ascending order.</details> 5107 <tag id="V1" /> 5108 </entry> 5109 <entry name="availableFilterDensities" type="float" visibility="public" 5110 container="array" hwlevel="full"> 5111 <array> 5112 <size>n</size> 5113 </array> 5114 <description> 5115 List of neutral density filter values for 5116 android.lens.filterDensity that are supported by this camera device. 5117 </description> 5118 <units>Exposure value (EV)</units> 5119 <range> 5120 Values are &gt;= 0 5121 </range> 5122 <details> 5123 If a neutral density filter is not supported by this camera device, 5124 this list will contain only 0. Otherwise, this list will include every 5125 filter density supported by the camera device, in ascending order. 5126 </details> 5127 <tag id="V1" /> 5128 </entry> 5129 <entry name="availableFocalLengths" type="float" visibility="public" 5130 type_notes="The list of available focal lengths" 5131 container="array" hwlevel="legacy"> 5132 <array> 5133 <size>n</size> 5134 </array> 5135 <description> 5136 List of focal lengths for android.lens.focalLength that are supported by this camera 5137 device. 5138 </description> 5139 <units>Millimeters</units> 5140 <range> 5141 Values are &gt; 0 5142 </range> 5143 <details> 5144 If optical zoom is not supported, this list will only contain 5145 a single value corresponding to the fixed focal length of the 5146 device. Otherwise, this list will include every focal length supported 5147 by the camera device, in ascending order. 5148 </details> 5149 <tag id="BC" /> 5150 <tag id="V1" /> 5151 </entry> 5152 <entry name="availableOpticalStabilization" type="byte" 5153 visibility="public" type_notes="list of enums" container="array" 5154 typedef="enumList" hwlevel="limited"> 5155 <array> 5156 <size>n</size> 5157 </array> 5158 <description> 5159 List of optical image stabilization (OIS) modes for 5160 android.lens.opticalStabilizationMode that are supported by this camera device. 5161 </description> 5162 <range>Any value listed in android.lens.opticalStabilizationMode</range> 5163 <details> 5164 If OIS is not supported by a given camera device, this list will 5165 contain only OFF. 5166 </details> 5167 <tag id="V1" /> 5168 </entry> 5169 <entry name="hyperfocalDistance" type="float" visibility="public" optional="true" 5170 hwlevel="limited" permission_needed="true"> 5171 <description>Hyperfocal distance for this lens.</description> 5172 <units>See android.lens.info.focusDistanceCalibration for details</units> 5173 <range>If lens is fixed focus, &gt;= 0. If lens has focuser unit, the value is 5174 within `(0.0f, android.lens.info.minimumFocusDistance]`</range> 5175 <details> 5176 If the lens is not fixed focus, the camera device will report this 5177 field when android.lens.info.focusDistanceCalibration is APPROXIMATE or CALIBRATED. 5178 </details> 5179 </entry> 5180 <entry name="minimumFocusDistance" type="float" visibility="public" optional="true" 5181 hwlevel="limited" permission_needed="true"> 5182 <description>Shortest distance from frontmost surface 5183 of the lens that can be brought into sharp focus.</description> 5184 <units>See android.lens.info.focusDistanceCalibration for details</units> 5185 <range>&gt;= 0</range> 5186 <details>If the lens is fixed-focus, this will be 5187 0.</details> 5188 <hal_details>Mandatory for FULL devices; LIMITED devices 5189 must always set this value to 0 for fixed-focus; and may omit 5190 the minimum focus distance otherwise. 5191 5192 This field is also mandatory for all devices advertising 5193 the MANUAL_SENSOR capability.</hal_details> 5194 <tag id="V1" /> 5195 </entry> 5196 <entry name="shadingMapSize" type="int32" visibility="ndk_public" 5197 type_notes="width and height (N, M) of lens shading map provided by the camera device." 5198 container="array" typedef="size" hwlevel="full"> 5199 <array> 5200 <size>2</size> 5201 </array> 5202 <description>Dimensions of lens shading map.</description> 5203 <range>Both values &gt;= 1</range> 5204 <details> 5205 The map should be on the order of 30-40 rows and columns, and 5206 must be smaller than 64x64. 5207 </details> 5208 <tag id="V1" /> 5209 </entry> 5210 <entry name="focusDistanceCalibration" type="byte" visibility="public" 5211 enum="true" hwlevel="limited"> 5212 <enum> 5213 <value>UNCALIBRATED 5214 <notes> 5215 The lens focus distance is not accurate, and the units used for 5216 android.lens.focusDistance do not correspond to any physical units. 5217 5218 Setting the lens to the same focus distance on separate occasions may 5219 result in a different real focus distance, depending on factors such 5220 as the orientation of the device, the age of the focusing mechanism, 5221 and the device temperature. The focus distance value will still be 5222 in the range of `[0, android.lens.info.minimumFocusDistance]`, where 0 5223 represents the farthest focus. 5224 </notes> 5225 </value> 5226 <value>APPROXIMATE 5227 <notes> 5228 The lens focus distance is measured in diopters. 5229 5230 However, setting the lens to the same focus distance 5231 on separate occasions may result in a different real 5232 focus distance, depending on factors such as the 5233 orientation of the device, the age of the focusing 5234 mechanism, and the device temperature. 5235 </notes> 5236 </value> 5237 <value>CALIBRATED 5238 <notes> 5239 The lens focus distance is measured in diopters, and 5240 is calibrated. 5241 5242 The lens mechanism is calibrated so that setting the 5243 same focus distance is repeatable on multiple 5244 occasions with good accuracy, and the focus distance 5245 corresponds to the real physical distance to the plane 5246 of best focus. 5247 </notes> 5248 </value> 5249 </enum> 5250 <description>The lens focus distance calibration quality.</description> 5251 <details> 5252 The lens focus distance calibration quality determines the reliability of 5253 focus related metadata entries, i.e. android.lens.focusDistance, 5254 android.lens.focusRange, android.lens.info.hyperfocalDistance, and 5255 android.lens.info.minimumFocusDistance. 5256 5257 APPROXIMATE and CALIBRATED devices report the focus metadata in 5258 units of diopters (1/meter), so `0.0f` represents focusing at infinity, 5259 and increasing positive numbers represent focusing closer and closer 5260 to the camera device. The focus distance control also uses diopters 5261 on these devices. 5262 5263 UNCALIBRATED devices do not use units that are directly comparable 5264 to any real physical measurement, but `0.0f` still represents farthest 5265 focus, and android.lens.info.minimumFocusDistance represents the 5266 nearest focus the device can achieve. 5267 </details> 5268 <hal_details> 5269 For devices advertise APPROXIMATE quality or higher, diopters 0 (infinity 5270 focus) must work. When autofocus is disabled (android.control.afMode == OFF) 5271 and the lens focus distance is set to 0 diopters 5272 (android.lens.focusDistance == 0), the lens will move to focus at infinity 5273 and is stably focused at infinity even if the device tilts. It may take the 5274 lens some time to move; during the move the lens state should be MOVING and 5275 the output diopter value should be changing toward 0. 5276 </hal_details> 5277 <tag id="V1" /> 5278 </entry> 5279 </namespace> 5280 <entry name="facing" type="byte" visibility="public" enum="true" hwlevel="legacy"> 5281 <enum> 5282 <value>FRONT 5283 <notes> 5284 The camera device faces the same direction as the device's screen. 5285 </notes></value> 5286 <value>BACK 5287 <notes> 5288 The camera device faces the opposite direction as the device's screen. 5289 </notes></value> 5290 <value>EXTERNAL 5291 <notes> 5292 The camera device is an external camera, and has no fixed facing relative to the 5293 device's screen. 5294 </notes></value> 5295 </enum> 5296 <description>Direction the camera faces relative to 5297 device screen.</description> 5298 </entry> 5299 <entry name="poseRotation" type="float" visibility="public" 5300 container="array" permission_needed="true"> 5301 <array> 5302 <size>4</size> 5303 </array> 5304 <description> 5305 The orientation of the camera relative to the sensor 5306 coordinate system. 5307 </description> 5308 <units> 5309 Quaternion coefficients 5310 </units> 5311 <details> 5312 The four coefficients that describe the quaternion 5313 rotation from the Android sensor coordinate system to a 5314 camera-aligned coordinate system where the X-axis is 5315 aligned with the long side of the image sensor, the Y-axis 5316 is aligned with the short side of the image sensor, and 5317 the Z-axis is aligned with the optical axis of the sensor. 5318 5319 To convert from the quaternion coefficients `(x,y,z,w)` 5320 to the axis of rotation `(a_x, a_y, a_z)` and rotation 5321 amount `theta`, the following formulas can be used: 5322 5323 theta = 2 * acos(w) 5324 a_x = x / sin(theta/2) 5325 a_y = y / sin(theta/2) 5326 a_z = z / sin(theta/2) 5327 5328 To create a 3x3 rotation matrix that applies the rotation 5329 defined by this quaternion, the following matrix can be 5330 used: 5331 5332 R = [ 1 - 2y^2 - 2z^2, 2xy - 2zw, 2xz + 2yw, 5333 2xy + 2zw, 1 - 2x^2 - 2z^2, 2yz - 2xw, 5334 2xz - 2yw, 2yz + 2xw, 1 - 2x^2 - 2y^2 ] 5335 5336 This matrix can then be used to apply the rotation to a 5337 column vector point with 5338 5339 `p' = Rp` 5340 5341 where `p` is in the device sensor coordinate system, and 5342 `p'` is in the camera-oriented coordinate system. 5343 5344 If android.lens.poseReference is UNDEFINED, the quaternion rotation cannot 5345 be accurately represented by the camera device, and will be represented by 5346 default values matching its default facing. 5347 </details> 5348 <tag id="DEPTH" /> 5349 </entry> 5350 <entry name="poseTranslation" type="float" visibility="public" 5351 container="array" permission_needed="true"> 5352 <array> 5353 <size>3</size> 5354 </array> 5355 <description>Position of the camera optical center.</description> 5356 <units>Meters</units> 5357 <details> 5358 The position of the camera device's lens optical center, 5359 as a three-dimensional vector `(x,y,z)`. 5360 5361 Prior to Android P, or when android.lens.poseReference is PRIMARY_CAMERA, this position 5362 is relative to the optical center of the largest camera device facing in the same 5363 direction as this camera, in the {@link android.hardware.SensorEvent Android sensor 5364 coordinate axes}. Note that only the axis definitions are shared with the sensor 5365 coordinate system, but not the origin. 5366 5367 If this device is the largest or only camera device with a given facing, then this 5368 position will be `(0, 0, 0)`; a camera device with a lens optical center located 3 cm 5369 from the main sensor along the +X axis (to the right from the user's perspective) will 5370 report `(0.03, 0, 0)`. Note that this means that, for many computer vision 5371 applications, the position needs to be negated to convert it to a translation from the 5372 camera to the origin. 5373 5374 To transform a pixel coordinates between two cameras facing the same direction, first 5375 the source camera android.lens.distortion must be corrected for. Then the source 5376 camera android.lens.intrinsicCalibration needs to be applied, followed by the 5377 android.lens.poseRotation of the source camera, the translation of the source camera 5378 relative to the destination camera, the android.lens.poseRotation of the destination 5379 camera, and finally the inverse of android.lens.intrinsicCalibration of the destination 5380 camera. This obtains a radial-distortion-free coordinate in the destination camera pixel 5381 coordinates. 5382 5383 To compare this against a real image from the destination camera, the destination camera 5384 image then needs to be corrected for radial distortion before comparison or sampling. 5385 5386 When android.lens.poseReference is GYROSCOPE, then this position is relative to 5387 the center of the primary gyroscope on the device. The axis definitions are the same as 5388 with PRIMARY_CAMERA. 5389 5390 When android.lens.poseReference is UNDEFINED, this position cannot be accurately 5391 represented by the camera device, and will be represented as `(0, 0, 0)`. 5392 5393 When android.lens.poseReference is AUTOMOTIVE, then this position is relative to the 5394 origin of the automotive sensor coordinate system, which is at the center of the rear 5395 axle. 5396 </details> 5397 <tag id="DEPTH" /> 5398 </entry> 5399 </static> 5400 <dynamic> 5401 <clone entry="android.lens.aperture" kind="controls"> 5402 <tag id="V1" /> 5403 </clone> 5404 <clone entry="android.lens.filterDensity" kind="controls"> 5405 <tag id="V1" /> 5406 </clone> 5407 <clone entry="android.lens.focalLength" kind="controls"> 5408 <tag id="BC" /> 5409 </clone> 5410 <clone entry="android.lens.focusDistance" kind="controls"> 5411 <details>Should be zero for fixed-focus cameras</details> 5412 <tag id="BC" /> 5413 </clone> 5414 <entry name="focusRange" type="float" visibility="public" 5415 type_notes="Range of scene distances that are in focus" 5416 container="array" typedef="pairFloatFloat" hwlevel="limited"> 5417 <array> 5418 <size>2</size> 5419 </array> 5420 <description>The range of scene distances that are in 5421 sharp focus (depth of field).</description> 5422 <units>A pair of focus distances in diopters: (near, 5423 far); see android.lens.info.focusDistanceCalibration for details.</units> 5424 <range>&gt;=0</range> 5425 <details>If variable focus not supported, can still report 5426 fixed depth of field range</details> 5427 <tag id="BC" /> 5428 </entry> 5429 <clone entry="android.lens.opticalStabilizationMode" 5430 kind="controls"> 5431 <tag id="V1" /> 5432 </clone> 5433 <entry name="state" type="byte" visibility="public" enum="true" hwlevel="limited"> 5434 <enum> 5435 <value>STATIONARY 5436 <notes> 5437 The lens parameters (android.lens.focalLength, android.lens.focusDistance, 5438 android.lens.filterDensity and android.lens.aperture) are not changing. 5439 </notes> 5440 </value> 5441 <value>MOVING 5442 <notes> 5443 One or several of the lens parameters 5444 (android.lens.focalLength, android.lens.focusDistance, 5445 android.lens.filterDensity or android.lens.aperture) is 5446 currently changing. 5447 </notes> 5448 </value> 5449 </enum> 5450 <description>Current lens status.</description> 5451 <details> 5452 For lens parameters android.lens.focalLength, android.lens.focusDistance, 5453 android.lens.filterDensity and android.lens.aperture, when changes are requested, 5454 they may take several frames to reach the requested values. This state indicates 5455 the current status of the lens parameters. 5456 5457 When the state is STATIONARY, the lens parameters are not changing. This could be 5458 either because the parameters are all fixed, or because the lens has had enough 5459 time to reach the most recently-requested values. 5460 If all these lens parameters are not changeable for a camera device, as listed below: 5461 5462 * Fixed focus (`android.lens.info.minimumFocusDistance == 0`), which means 5463 android.lens.focusDistance parameter will always be 0. 5464 * Fixed focal length (android.lens.info.availableFocalLengths contains single value), 5465 which means the optical zoom is not supported. 5466 * No ND filter (android.lens.info.availableFilterDensities contains only 0). 5467 * Fixed aperture (android.lens.info.availableApertures contains single value). 5468 5469 Then this state will always be STATIONARY. 5470 5471 When the state is MOVING, it indicates that at least one of the lens parameters 5472 is changing. 5473 </details> 5474 <tag id="V1" /> 5475 </entry> 5476 <clone entry="android.lens.poseRotation" kind="static"> 5477 </clone> 5478 <clone entry="android.lens.poseTranslation" kind="static"> 5479 </clone> 5480 </dynamic> 5481 <static> 5482 <entry name="intrinsicCalibration" type="float" visibility="public" 5483 container="array" permission_needed="true"> 5484 <array> 5485 <size>5</size> 5486 </array> 5487 <description> 5488 The parameters for this camera device's intrinsic 5489 calibration. 5490 </description> 5491 <units> 5492 Pixels in the 5493 android.sensor.info.preCorrectionActiveArraySize 5494 coordinate system. 5495 </units> 5496 <details> 5497 The five calibration parameters that describe the 5498 transform from camera-centric 3D coordinates to sensor 5499 pixel coordinates: 5500 5501 [f_x, f_y, c_x, c_y, s] 5502 5503 Where `f_x` and `f_y` are the horizontal and vertical 5504 focal lengths, `[c_x, c_y]` is the position of the optical 5505 axis, and `s` is a skew parameter for the sensor plane not 5506 being aligned with the lens plane. 5507 5508 These are typically used within a transformation matrix K: 5509 5510 K = [ f_x, s, c_x, 5511 0, f_y, c_y, 5512 0 0, 1 ] 5513 5514 which can then be combined with the camera pose rotation 5515 `R` and translation `t` (android.lens.poseRotation and 5516 android.lens.poseTranslation, respectively) to calculate the 5517 complete transform from world coordinates to pixel 5518 coordinates: 5519 5520 P = [ K 0 * [ R -Rt 5521 0 1 ] 0 1 ] 5522 5523 (Note the negation of poseTranslation when mapping from camera 5524 to world coordinates, and multiplication by the rotation). 5525 5526 With `p_w` being a point in the world coordinate system 5527 and `p_s` being a point in the camera active pixel array 5528 coordinate system, and with the mapping including the 5529 homogeneous division by z: 5530 5531 p_h = (x_h, y_h, z_h) = P p_w 5532 p_s = p_h / z_h 5533 5534 so `[x_s, y_s]` is the pixel coordinates of the world 5535 point, `z_s = 1`, and `w_s` is a measurement of disparity 5536 (depth) in pixel coordinates. 5537 5538 Note that the coordinate system for this transform is the 5539 android.sensor.info.preCorrectionActiveArraySize system, 5540 where `(0,0)` is the top-left of the 5541 preCorrectionActiveArraySize rectangle. Once the pose and 5542 intrinsic calibration transforms have been applied to a 5543 world point, then the android.lens.distortion 5544 transform needs to be applied, and the result adjusted to 5545 be in the android.sensor.info.activeArraySize coordinate 5546 system (where `(0, 0)` is the top-left of the 5547 activeArraySize rectangle), to determine the final pixel 5548 coordinate of the world point for processed (non-RAW) 5549 output buffers. 5550 5551 For camera devices, the center of pixel `(x,y)` is located at 5552 coordinate `(x + 0.5, y + 0.5)`. So on a device with a 5553 precorrection active array of size `(10,10)`, the valid pixel 5554 indices go from `(0,0)-(9,9)`, and an perfectly-built camera would 5555 have an optical center at the exact center of the pixel grid, at 5556 coordinates `(5.0, 5.0)`, which is the top-left corner of pixel 5557 `(5,5)`. 5558 </details> 5559 <tag id="DEPTH" /> 5560 </entry> 5561 <entry name="radialDistortion" type="float" visibility="public" 5562 deprecated="true" container="array" permission_needed="true"> 5563 <array> 5564 <size>6</size> 5565 </array> 5566 <description> 5567 The correction coefficients to correct for this camera device's 5568 radial and tangential lens distortion. 5569 </description> 5570 <deprecation_description> 5571 This field was inconsistently defined in terms of its 5572 normalization. Use android.lens.distortion instead. 5573 </deprecation_description> 5574 <units> 5575 Unitless coefficients. 5576 </units> 5577 <details> 5578 Four radial distortion coefficients `[kappa_0, kappa_1, kappa_2, 5579 kappa_3]` and two tangential distortion coefficients 5580 `[kappa_4, kappa_5]` that can be used to correct the 5581 lens's geometric distortion with the mapping equations: 5582 5583 x_c = x_i * ( kappa_0 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 5584 kappa_4 * (2 * x_i * y_i) + kappa_5 * ( r^2 + 2 * x_i^2 ) 5585 y_c = y_i * ( kappa_0 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 5586 kappa_5 * (2 * x_i * y_i) + kappa_4 * ( r^2 + 2 * y_i^2 ) 5587 5588 Here, `[x_c, y_c]` are the coordinates to sample in the 5589 input image that correspond to the pixel values in the 5590 corrected image at the coordinate `[x_i, y_i]`: 5591 5592 correctedImage(x_i, y_i) = sample_at(x_c, y_c, inputImage) 5593 5594 The pixel coordinates are defined in a normalized 5595 coordinate system related to the 5596 android.lens.intrinsicCalibration calibration fields. 5597 Both `[x_i, y_i]` and `[x_c, y_c]` have `(0,0)` at the 5598 lens optical center `[c_x, c_y]`. The maximum magnitudes 5599 of both x and y coordinates are normalized to be 1 at the 5600 edge further from the optical center, so the range 5601 for both dimensions is `-1 <= x <= 1`. 5602 5603 Finally, `r` represents the radial distance from the 5604 optical center, `r^2 = x_i^2 + y_i^2`, and its magnitude 5605 is therefore no larger than `|r| <= sqrt(2)`. 5606 5607 The distortion model used is the Brown-Conrady model. 5608 </details> 5609 <tag id="DEPTH" /> 5610 </entry> 5611 </static> 5612 <dynamic> 5613 <clone entry="android.lens.intrinsicCalibration" kind="static"> 5614 </clone> 5615 <clone entry="android.lens.radialDistortion" kind="static"> 5616 </clone> 5617 </dynamic> 5618 <static> 5619 <entry name="poseReference" type="byte" visibility="public" enum="true" 5620 permission_needed="true" hal_version="3.3" > 5621 <enum> 5622 <value>PRIMARY_CAMERA 5623 <notes>The value of android.lens.poseTranslation is relative to the optical center of 5624 the largest camera device facing the same direction as this camera. 5625 5626 This is the default value for API levels before Android P. 5627 </notes> 5628 </value> 5629 <value>GYROSCOPE 5630 <notes>The value of android.lens.poseTranslation is relative to the position of the 5631 primary gyroscope of this Android device. 5632 </notes> 5633 </value> 5634 <value hal_version="3.5">UNDEFINED 5635 <notes>The camera device cannot represent the values of android.lens.poseTranslation 5636 and android.lens.poseRotation accurately enough. One such example is a camera device 5637 on the cover of a foldable phone: in order to measure the pose translation and rotation, 5638 some kind of hinge position sensor would be needed. 5639 5640 The value of android.lens.poseTranslation must be all zeros, and 5641 android.lens.poseRotation must be values matching its default facing. 5642 </notes> 5643 </value> 5644 <value hal_version="3.8">AUTOMOTIVE 5645 <notes>The value of android.lens.poseTranslation is relative to the origin of the 5646 automotive sensor coordinate system, which is at the center of the rear axle. 5647 </notes> 5648 </value> 5649 </enum> 5650 <description> 5651 The origin for android.lens.poseTranslation, and the accuracy of 5652 android.lens.poseTranslation and android.lens.poseRotation. 5653 </description> 5654 <details> 5655 Different calibration methods and use cases can produce better or worse results 5656 depending on the selected coordinate origin. 5657 </details> 5658 </entry> 5659 <entry name="distortion" type="float" visibility="public" container="array" 5660 permission_needed="true" hal_version="3.3" > 5661 <array> 5662 <size>5</size> 5663 </array> 5664 <description> 5665 The correction coefficients to correct for this camera device's 5666 radial and tangential lens distortion. 5667 5668 Replaces the deprecated android.lens.radialDistortion field, which was 5669 inconsistently defined. 5670 </description> 5671 <units> 5672 Unitless coefficients. 5673 </units> 5674 <details> 5675 Three radial distortion coefficients `[kappa_1, kappa_2, 5676 kappa_3]` and two tangential distortion coefficients 5677 `[kappa_4, kappa_5]` that can be used to correct the 5678 lens's geometric distortion with the mapping equations: 5679 5680 x_c = x_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 5681 kappa_4 * (2 * x_i * y_i) + kappa_5 * ( r^2 + 2 * x_i^2 ) 5682 y_c = y_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 5683 kappa_5 * (2 * x_i * y_i) + kappa_4 * ( r^2 + 2 * y_i^2 ) 5684 5685 Here, `[x_c, y_c]` are the coordinates to sample in the 5686 input image that correspond to the pixel values in the 5687 corrected image at the coordinate `[x_i, y_i]`: 5688 5689 correctedImage(x_i, y_i) = sample_at(x_c, y_c, inputImage) 5690 5691 The pixel coordinates are defined in a coordinate system 5692 related to the android.lens.intrinsicCalibration 5693 calibration fields; see that entry for details of the mapping stages. 5694 Both `[x_i, y_i]` and `[x_c, y_c]` 5695 have `(0,0)` at the lens optical center `[c_x, c_y]`, and 5696 the range of the coordinates depends on the focal length 5697 terms of the intrinsic calibration. 5698 5699 Finally, `r` represents the radial distance from the 5700 optical center, `r^2 = x_i^2 + y_i^2`. 5701 5702 The distortion model used is the Brown-Conrady model. 5703 </details> 5704 <tag id="DEPTH" /> 5705 </entry> 5706 <entry name="distortionMaximumResolution" type="float" visibility="public" container="array" 5707 permission_needed="true" hal_version="3.6" > 5708 <array> 5709 <size>5</size> 5710 </array> 5711 <description> 5712 The correction coefficients to correct for this camera device's 5713 radial and tangential lens distortion for a 5714 CaptureRequest with android.sensor.pixelMode set to 5715 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 5716 </description> 5717 <units> 5718 Unitless coefficients. 5719 </units> 5720 <details> 5721 Analogous to android.lens.distortion, when android.sensor.pixelMode is set to 5722 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 5723 </details> 5724 <tag id="DEPTH" /> 5725 </entry> 5726 <entry name="intrinsicCalibrationMaximumResolution" type="float" visibility="public" 5727 container="array" permission_needed="true" hal_version="3.6"> 5728 <array> 5729 <size>5</size> 5730 </array> 5731 <description> 5732 The parameters for this camera device's intrinsic 5733 calibration when android.sensor.pixelMode is set to 5734 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 5735 </description> 5736 <units> 5737 Pixels in the 5738 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution 5739 coordinate system. 5740 </units> 5741 <details> 5742 Analogous to android.lens.intrinsicCalibration, when android.sensor.pixelMode is set to 5743 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 5744 </details> 5745 <tag id="DEPTH" /> 5746 </entry> 5747 </static> 5748 <dynamic> 5749 <clone entry="android.lens.distortion" kind="static"> 5750 </clone> 5751 </dynamic> 5752 </section> 5753 <section name="noiseReduction"> 5754 <controls> 5755 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 5756 <enum> 5757 <value>OFF 5758 <notes>No noise reduction is applied.</notes></value> 5759 <value>FAST 5760 <notes>Noise reduction is applied without reducing frame rate relative to sensor 5761 output. It may be the same as OFF if noise reduction will reduce frame rate 5762 relative to sensor.</notes></value> 5763 <value>HIGH_QUALITY 5764 <notes>High-quality noise reduction is applied, at the cost of possibly reduced frame 5765 rate relative to sensor output.</notes></value> 5766 <value optional="true">MINIMAL 5767 <notes>MINIMAL noise reduction is applied without reducing frame rate relative to 5768 sensor output. </notes></value> 5769 <value optional="true">ZERO_SHUTTER_LAG 5770 5771 <notes>Noise reduction is applied at different levels for different output streams, 5772 based on resolution. Streams at maximum recording resolution (see {@link 5773 android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession}) 5774 or below have noise reduction applied, while higher-resolution streams have MINIMAL (if 5775 supported) or no noise reduction applied (if MINIMAL is not supported.) The degree of 5776 noise reduction for low-resolution streams is tuned so that frame rate is not impacted, 5777 and the quality is equal to or better than FAST (since it is only applied to 5778 lower-resolution outputs, quality may improve from FAST). 5779 5780 This mode is intended to be used by applications operating in a zero-shutter-lag mode 5781 with YUV or PRIVATE reprocessing, where the application continuously captures 5782 high-resolution intermediate buffers into a circular buffer, from which a final image is 5783 produced via reprocessing when a user takes a picture. For such a use case, the 5784 high-resolution buffers must not have noise reduction applied to maximize efficiency of 5785 preview and to avoid over-applying noise filtering when reprocessing, while 5786 low-resolution buffers (used for recording or preview, generally) need noise reduction 5787 applied for reasonable preview quality. 5788 5789 This mode is guaranteed to be supported by devices that support either the 5790 YUV_REPROCESSING or PRIVATE_REPROCESSING capabilities 5791 (android.request.availableCapabilities lists either of those capabilities) and it will 5792 be the default mode for CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template. 5793 </notes></value> 5794 </enum> 5795 <description>Mode of operation for the noise reduction algorithm.</description> 5796 <range>android.noiseReduction.availableNoiseReductionModes</range> 5797 <details>The noise reduction algorithm attempts to improve image quality by removing 5798 excessive noise added by the capture process, especially in dark conditions. 5799 5800 OFF means no noise reduction will be applied by the camera device, for both raw and 5801 YUV domain. 5802 5803 MINIMAL means that only sensor raw domain basic noise reduction is enabled ,to remove 5804 demosaicing or other processing artifacts. For YUV_REPROCESSING, MINIMAL is same as OFF. 5805 This mode is optional, may not be support by all devices. The application should check 5806 android.noiseReduction.availableNoiseReductionModes before using it. 5807 5808 FAST/HIGH_QUALITY both mean camera device determined noise filtering 5809 will be applied. HIGH_QUALITY mode indicates that the camera device 5810 will use the highest-quality noise filtering algorithms, 5811 even if it slows down capture rate. FAST means the camera device will not 5812 slow down capture rate when applying noise filtering. FAST may be the same as MINIMAL if 5813 MINIMAL is listed, or the same as OFF if any noise filtering will slow down capture rate. 5814 Every output stream will have a similar amount of enhancement applied. 5815 5816 ZERO_SHUTTER_LAG is meant to be used by applications that maintain a continuous circular 5817 buffer of high-resolution images during preview and reprocess image(s) from that buffer 5818 into a final capture when triggered by the user. In this mode, the camera device applies 5819 noise reduction to low-resolution streams (below maximum recording resolution) to maximize 5820 preview quality, but does not apply noise reduction to high-resolution streams, since 5821 those will be reprocessed later if necessary. 5822 5823 For YUV_REPROCESSING, these FAST/HIGH_QUALITY modes both mean that the camera device 5824 will apply FAST/HIGH_QUALITY YUV domain noise reduction, respectively. The camera device 5825 may adjust the noise reduction parameters for best image quality based on the 5826 android.reprocess.effectiveExposureFactor if it is set. 5827 </details> 5828 <hal_details> 5829 For YUV_REPROCESSING The HAL can use android.reprocess.effectiveExposureFactor to 5830 adjust the internal noise reduction parameters appropriately to get the best quality 5831 images. 5832 </hal_details> 5833 <tag id="V1" /> 5834 <tag id="REPROC" /> 5835 </entry> 5836 <entry name="strength" type="byte"> 5837 <description>Control the amount of noise reduction 5838 applied to the images</description> 5839 <units>1-10; 10 is max noise reduction</units> 5840 <range>1 - 10</range> 5841 <tag id="FUTURE" /> 5842 </entry> 5843 </controls> 5844 <static> 5845 <entry name="availableNoiseReductionModes" type="byte" visibility="public" 5846 type_notes="list of enums" container="array" typedef="enumList" hwlevel="limited"> 5847 <array> 5848 <size>n</size> 5849 </array> 5850 <description> 5851 List of noise reduction modes for android.noiseReduction.mode that are supported 5852 by this camera device. 5853 </description> 5854 <range>Any value listed in android.noiseReduction.mode</range> 5855 <details> 5856 Full-capability camera devices will always support OFF and FAST. 5857 5858 Camera devices that support YUV_REPROCESSING or PRIVATE_REPROCESSING will support 5859 ZERO_SHUTTER_LAG. 5860 5861 Legacy-capability camera devices will only support FAST mode. 5862 </details> 5863 <hal_details> 5864 HAL must support both FAST and HIGH_QUALITY if noise reduction control is available 5865 on the camera device, but the underlying implementation can be the same for both modes. 5866 That is, if the highest quality implementation on the camera device does not slow down 5867 capture rate, then FAST and HIGH_QUALITY will generate the same output. 5868 </hal_details> 5869 <tag id="V1" /> 5870 <tag id="REPROC" /> 5871 </entry> 5872 </static> 5873 <dynamic> 5874 <clone entry="android.noiseReduction.mode" kind="controls"> 5875 <tag id="V1" /> 5876 <tag id="REPROC" /> 5877 </clone> 5878 </dynamic> 5879 </section> 5880 <section name="quirks"> 5881 <static> 5882 <entry name="meteringCropRegion" type="byte" visibility="system" deprecated="true" optional="true"> 5883 <description>If set to 1, the camera service does not 5884 scale 'normalized' coordinates with respect to the crop 5885 region. This applies to metering input (a{e,f,wb}Region 5886 and output (face rectangles).</description> 5887 <deprecation_description> 5888 Not used in HALv3 or newer 5889 </deprecation_description> 5890 <details>Normalized coordinates refer to those in the 5891 (-1000,1000) range mentioned in the 5892 android.hardware.Camera API. 5893 5894 HAL implementations should instead always use and emit 5895 sensor array-relative coordinates for all region data. Does 5896 not need to be listed in static metadata. Support will be 5897 removed in future versions of camera service.</details> 5898 </entry> 5899 <entry name="triggerAfWithAuto" type="byte" visibility="system" deprecated="true" optional="true"> 5900 <description>If set to 1, then the camera service always 5901 switches to FOCUS_MODE_AUTO before issuing a AF 5902 trigger.</description> 5903 <deprecation_description> 5904 Not used in HALv3 or newer 5905 </deprecation_description> 5906 <details>HAL implementations should implement AF trigger 5907 modes for AUTO, MACRO, CONTINUOUS_FOCUS, and 5908 CONTINUOUS_PICTURE modes instead of using this flag. Does 5909 not need to be listed in static metadata. Support will be 5910 removed in future versions of camera service</details> 5911 </entry> 5912 <entry name="useZslFormat" type="byte" visibility="system" deprecated="true" optional="true"> 5913 <description>If set to 1, the camera service uses 5914 CAMERA2_PIXEL_FORMAT_ZSL instead of 5915 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED for the zero 5916 shutter lag stream</description> 5917 <deprecation_description> 5918 Not used in HALv3 or newer 5919 </deprecation_description> 5920 <details>HAL implementations should use gralloc usage flags 5921 to determine that a stream will be used for 5922 zero-shutter-lag, instead of relying on an explicit 5923 format setting. Does not need to be listed in static 5924 metadata. Support will be removed in future versions of 5925 camera service.</details> 5926 </entry> 5927 <entry name="usePartialResult" type="byte" visibility="hidden" deprecated="true" optional="true"> 5928 <description> 5929 If set to 1, the HAL will always split result 5930 metadata for a single capture into multiple buffers, 5931 returned using multiple process_capture_result calls. 5932 </description> 5933 <deprecation_description> 5934 Not used in HALv3 or newer; replaced by better partials mechanism 5935 </deprecation_description> 5936 <details> 5937 Does not need to be listed in static 5938 metadata. Support for partial results will be reworked in 5939 future versions of camera service. This quirk will stop 5940 working at that point; DO NOT USE without careful 5941 consideration of future support. 5942 </details> 5943 <hal_details> 5944 Refer to `camera3_capture_result::partial_result` 5945 for information on how to implement partial results. 5946 </hal_details> 5947 </entry> 5948 </static> 5949 <dynamic> 5950 <entry name="partialResult" type="byte" visibility="hidden" deprecated="true" optional="true" enum="true" typedef="boolean"> 5951 <enum> 5952 <value>FINAL 5953 <notes>The last or only metadata result buffer 5954 for this capture.</notes> 5955 </value> 5956 <value>PARTIAL 5957 <notes>A partial buffer of result metadata for this 5958 capture. More result buffers for this capture will be sent 5959 by the camera device, the last of which will be marked 5960 FINAL.</notes> 5961 </value> 5962 </enum> 5963 <description> 5964 Whether a result given to the framework is the 5965 final one for the capture, or only a partial that contains a 5966 subset of the full set of dynamic metadata 5967 values.</description> 5968 <deprecation_description> 5969 Not used in HALv3 or newer 5970 </deprecation_description> 5971 <range>Optional. Default value is FINAL.</range> 5972 <details> 5973 The entries in the result metadata buffers for a 5974 single capture may not overlap, except for this entry. The 5975 FINAL buffers must retain FIFO ordering relative to the 5976 requests that generate them, so the FINAL buffer for frame 3 must 5977 always be sent to the framework after the FINAL buffer for frame 2, and 5978 before the FINAL buffer for frame 4. PARTIAL buffers may be returned 5979 in any order relative to other frames, but all PARTIAL buffers for a given 5980 capture must arrive before the FINAL buffer for that capture. This entry may 5981 only be used by the camera device if quirks.usePartialResult is set to 1. 5982 </details> 5983 <hal_details> 5984 Refer to `camera3_capture_result::partial_result` 5985 for information on how to implement partial results. 5986 </hal_details> 5987 </entry> 5988 </dynamic> 5989 </section> 5990 <section name="request"> 5991 <controls> 5992 <entry name="frameCount" type="int32" visibility="system" deprecated="true"> 5993 <description>A frame counter set by the framework. Must 5994 be maintained unchanged in output frame. This value monotonically 5995 increases with every new result (that is, each new result has a unique 5996 frameCount value). 5997 </description> 5998 <deprecation_description> 5999 Not used in HALv3 or newer 6000 </deprecation_description> 6001 <units>incrementing integer</units> 6002 <range>Any int.</range> 6003 </entry> 6004 <entry name="id" type="int32" visibility="hidden"> 6005 <description>An application-specified ID for the current 6006 request. Must be maintained unchanged in output 6007 frame</description> 6008 <units>arbitrary integer assigned by application</units> 6009 <range>Any int</range> 6010 <tag id="V1" /> 6011 </entry> 6012 <entry name="inputStreams" type="int32" visibility="system" deprecated="true" 6013 container="array"> 6014 <array> 6015 <size>n</size> 6016 </array> 6017 <description>List which camera reprocess stream is used 6018 for the source of reprocessing data.</description> 6019 <deprecation_description> 6020 Not used in HALv3 or newer 6021 </deprecation_description> 6022 <units>List of camera reprocess stream IDs</units> 6023 <range> 6024 Typically, only one entry allowed, must be a valid reprocess stream ID. 6025 </range> 6026 <details>Only meaningful when android.request.type == 6027 REPROCESS. Ignored otherwise</details> 6028 <tag id="HAL2" /> 6029 </entry> 6030 <entry name="metadataMode" type="byte" visibility="system" 6031 enum="true"> 6032 <enum> 6033 <value>NONE 6034 <notes>No metadata should be produced on output, except 6035 for application-bound buffer data. If no 6036 application-bound streams exist, no frame should be 6037 placed in the output frame queue. If such streams 6038 exist, a frame should be placed on the output queue 6039 with null metadata but with the necessary output buffer 6040 information. Timestamp information should still be 6041 included with any output stream buffers</notes></value> 6042 <value>FULL 6043 <notes>All metadata should be produced. Statistics will 6044 only be produced if they are separately 6045 enabled</notes></value> 6046 </enum> 6047 <description>How much metadata to produce on 6048 output</description> 6049 <tag id="FUTURE" /> 6050 </entry> 6051 <entry name="outputStreams" type="int32" visibility="system" deprecated="true" 6052 container="array"> 6053 <array> 6054 <size>n</size> 6055 </array> 6056 <description>Lists which camera output streams image data 6057 from this capture must be sent to</description> 6058 <deprecation_description> 6059 Not used in HALv3 or newer 6060 </deprecation_description> 6061 <units>List of camera stream IDs</units> 6062 <range>List must only include streams that have been 6063 created</range> 6064 <details>If no output streams are listed, then the image 6065 data should simply be discarded. The image data must 6066 still be captured for metadata and statistics production, 6067 and the lens and flash must operate as requested.</details> 6068 <tag id="HAL2" /> 6069 </entry> 6070 <entry name="type" type="byte" visibility="system" deprecated="true" enum="true"> 6071 <enum> 6072 <value>CAPTURE 6073 <notes>Capture a new image from the imaging hardware, 6074 and process it according to the 6075 settings</notes></value> 6076 <value>REPROCESS 6077 <notes>Process previously captured data; the 6078 android.request.inputStreams parameter determines the 6079 source reprocessing stream. TODO: Mark dynamic metadata 6080 needed for reprocessing with [RP]</notes></value> 6081 </enum> 6082 <description>The type of the request; either CAPTURE or 6083 REPROCESS. For legacy HAL3, this tag is redundant. 6084 </description> 6085 <deprecation_description> 6086 Not used in HALv3 or newer 6087 </deprecation_description> 6088 <tag id="HAL2" /> 6089 </entry> 6090 </controls> 6091 <static> 6092 <entry name="maxNumOutputStreams" type="int32" visibility="ndk_public" 6093 container="array" hwlevel="legacy"> 6094 <array> 6095 <size>3</size> 6096 </array> 6097 <description>The maximum numbers of different types of output streams 6098 that can be configured and used simultaneously by a camera device. 6099 </description> 6100 <range> 6101 For processed (and stalling) format streams, &gt;= 1. 6102 6103 For Raw format (either stalling or non-stalling) streams, &gt;= 0. 6104 6105 For processed (but not stalling) format streams, &gt;= 3 6106 for FULL mode devices (`android.info.supportedHardwareLevel == FULL`); 6107 &gt;= 2 for LIMITED mode devices (`android.info.supportedHardwareLevel == LIMITED`). 6108 </range> 6109 <details> 6110 This is a 3 element tuple that contains the max number of output simultaneous 6111 streams for raw sensor, processed (but not stalling), and processed (and stalling) 6112 formats respectively. For example, assuming that JPEG is typically a processed and 6113 stalling stream, if max raw sensor format output stream number is 1, max YUV streams 6114 number is 3, and max JPEG stream number is 2, then this tuple should be `(1, 3, 2)`. 6115 6116 This lists the upper bound of the number of output streams supported by 6117 the camera device. Using more streams simultaneously may require more hardware and 6118 CPU resources that will consume more power. The image format for an output stream can 6119 be any supported format provided by android.scaler.availableStreamConfigurations. 6120 The formats defined in android.scaler.availableStreamConfigurations can be categorized 6121 into the 3 stream types as below: 6122 6123 * Processed (but stalling): any non-RAW format with a stallDurations &gt; 0. 6124 Typically {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG format}. 6125 * Raw formats: {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16 6126 RAW_SENSOR}, {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10 RAW10}, or 6127 {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12 RAW12}. 6128 * Processed (but not-stalling): any non-RAW format without a stall duration. Typically 6129 {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888 YUV_420_888}, 6130 {@link android.graphics.ImageFormat#NV21 NV21}, {@link 6131 android.graphics.ImageFormat#YV12 YV12}, or {@link 6132 android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} . 6133 </details> 6134 <tag id="BC" /> 6135 </entry> 6136 <entry name="maxNumOutputRaw" type="int32" visibility="java_public" synthetic="true" 6137 hwlevel="legacy"> 6138 <description>The maximum numbers of different types of output streams 6139 that can be configured and used simultaneously by a camera device 6140 for any `RAW` formats. 6141 </description> 6142 <range> 6143 &gt;= 0 6144 </range> 6145 <details> 6146 This value contains the max number of output simultaneous 6147 streams from the raw sensor. 6148 6149 This lists the upper bound of the number of output streams supported by 6150 the camera device. Using more streams simultaneously may require more hardware and 6151 CPU resources that will consume more power. The image format for this kind of an output stream can 6152 be any `RAW` and supported format provided by android.scaler.streamConfigurationMap. 6153 6154 In particular, a `RAW` format is typically one of: 6155 6156 * {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16 RAW_SENSOR} 6157 * {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10 RAW10} 6158 * {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12 RAW12} 6159 6160 LEGACY mode devices (android.info.supportedHardwareLevel `==` LEGACY) 6161 never support raw streams. 6162 </details> 6163 </entry> 6164 <entry name="maxNumOutputProc" type="int32" visibility="java_public" synthetic="true" 6165 hwlevel="legacy"> 6166 <description>The maximum numbers of different types of output streams 6167 that can be configured and used simultaneously by a camera device 6168 for any processed (but not-stalling) formats. 6169 </description> 6170 <range> 6171 &gt;= 3 6172 for FULL mode devices (`android.info.supportedHardwareLevel == FULL`); 6173 &gt;= 2 for LIMITED mode devices (`android.info.supportedHardwareLevel == LIMITED`). 6174 </range> 6175 <details> 6176 This value contains the max number of output simultaneous 6177 streams for any processed (but not-stalling) formats. 6178 6179 This lists the upper bound of the number of output streams supported by 6180 the camera device. Using more streams simultaneously may require more hardware and 6181 CPU resources that will consume more power. The image format for this kind of an output stream can 6182 be any non-`RAW` and supported format provided by android.scaler.streamConfigurationMap. 6183 6184 Processed (but not-stalling) is defined as any non-RAW format without a stall duration. 6185 Typically: 6186 6187 * {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888 YUV_420_888} 6188 * {@link android.graphics.ImageFormat#NV21 NV21} 6189 * {@link android.graphics.ImageFormat#YV12 YV12} 6190 * Implementation-defined formats, i.e. {@link 6191 android.hardware.camera2.params.StreamConfigurationMap#isOutputSupportedFor(Class)} 6192 * {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} 6193 6194 For full guarantees, query {@link 6195 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration} with a 6196 processed format -- it will return 0 for a non-stalling stream. 6197 6198 LEGACY devices will support at least 2 processing/non-stalling streams. 6199 </details> 6200 </entry> 6201 <entry name="maxNumOutputProcStalling" type="int32" visibility="java_public" synthetic="true" 6202 hwlevel="legacy"> 6203 <description>The maximum numbers of different types of output streams 6204 that can be configured and used simultaneously by a camera device 6205 for any processed (and stalling) formats. 6206 </description> 6207 <range> 6208 &gt;= 1 6209 </range> 6210 <details> 6211 This value contains the max number of output simultaneous 6212 streams for any processed (but not-stalling) formats. 6213 6214 This lists the upper bound of the number of output streams supported by 6215 the camera device. Using more streams simultaneously may require more hardware and 6216 CPU resources that will consume more power. The image format for this kind of an output stream can 6217 be any non-`RAW` and supported format provided by android.scaler.streamConfigurationMap. 6218 6219 A processed and stalling format is defined as any non-RAW format with a stallDurations 6220 &gt; 0. Typically only the {@link 6221 android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG format} is a stalling format. 6222 6223 For full guarantees, query {@link 6224 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration} with a 6225 processed format -- it will return a non-0 value for a stalling stream. 6226 6227 LEGACY devices will support up to 1 processing/stalling stream. 6228 </details> 6229 </entry> 6230 <entry name="maxNumReprocessStreams" type="int32" visibility="system" 6231 deprecated="true" container="array"> 6232 <array> 6233 <size>1</size> 6234 </array> 6235 <description>How many reprocessing streams of any type 6236 can be allocated at the same time.</description> 6237 <deprecation_description> 6238 Not used in HALv3 or newer 6239 </deprecation_description> 6240 <range>&gt;= 0</range> 6241 <details> 6242 Only used by HAL2.x. 6243 6244 When set to 0, it means no reprocess stream is supported. 6245 </details> 6246 <tag id="HAL2" /> 6247 </entry> 6248 <entry name="maxNumInputStreams" type="int32" visibility="java_public" hwlevel="full"> 6249 <description> 6250 The maximum numbers of any type of input streams 6251 that can be configured and used simultaneously by a camera device. 6252 </description> 6253 <range> 6254 0 or 1. 6255 </range> 6256 <details>When set to 0, it means no input stream is supported. 6257 6258 The image format for a input stream can be any supported format returned by {@link 6259 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. When using an 6260 input stream, there must be at least one output stream configured to to receive the 6261 reprocessed images. 6262 6263 When an input stream and some output streams are used in a reprocessing request, 6264 only the input buffer will be used to produce these output stream buffers, and a 6265 new sensor image will not be captured. 6266 6267 For example, for Zero Shutter Lag (ZSL) still capture use case, the input 6268 stream image format will be PRIVATE, the associated output stream image format 6269 should be JPEG. 6270 </details> 6271 <hal_details> 6272 For the reprocessing flow and controls, see 6273 hardware/libhardware/include/hardware/camera3.h Section 10 for more details. 6274 </hal_details> 6275 <tag id="REPROC" /> 6276 </entry> 6277 </static> 6278 <dynamic> 6279 <entry name="frameCount" type="int32" visibility="hidden" deprecated="true"> 6280 <description>A frame counter set by the framework. This value monotonically 6281 increases with every new result (that is, each new result has a unique 6282 frameCount value).</description> 6283 <deprecation_description> 6284 Not used in HALv3 or newer 6285 </deprecation_description> 6286 <units>count of frames</units> 6287 <range>&gt; 0</range> 6288 <details>Reset on release()</details> 6289 </entry> 6290 <clone entry="android.request.id" kind="controls"></clone> 6291 <clone entry="android.request.metadataMode" 6292 kind="controls"></clone> 6293 <clone entry="android.request.outputStreams" 6294 kind="controls"></clone> 6295 <entry name="pipelineDepth" type="byte" visibility="public" hwlevel="legacy"> 6296 <description>Specifies the number of pipeline stages the frame went 6297 through from when it was exposed to when the final completed result 6298 was available to the framework.</description> 6299 <range>&lt;= android.request.pipelineMaxDepth</range> 6300 <details>Depending on what settings are used in the request, and 6301 what streams are configured, the data may undergo less processing, 6302 and some pipeline stages skipped. 6303 6304 See android.request.pipelineMaxDepth for more details. 6305 </details> 6306 <hal_details> 6307 This value must always represent the accurate count of how many 6308 pipeline stages were actually used. 6309 </hal_details> 6310 </entry> 6311 </dynamic> 6312 <static> 6313 <entry name="pipelineMaxDepth" type="byte" visibility="public" hwlevel="legacy"> 6314 <description>Specifies the number of maximum pipeline stages a frame 6315 has to go through from when it's exposed to when it's available 6316 to the framework.</description> 6317 <details>A typical minimum value for this is 2 (one stage to expose, 6318 one stage to readout) from the sensor. The ISP then usually adds 6319 its own stages to do custom HW processing. Further stages may be 6320 added by SW processing. 6321 6322 Depending on what settings are used (e.g. YUV, JPEG) and what 6323 processing is enabled (e.g. face detection), the actual pipeline 6324 depth (specified by android.request.pipelineDepth) may be less than 6325 the max pipeline depth. 6326 6327 A pipeline depth of X stages is equivalent to a pipeline latency of 6328 X frame intervals. 6329 6330 This value will normally be 8 or less, however, for high speed capture session, 6331 the max pipeline depth will be up to 8 x size of high speed capture request list. 6332 </details> 6333 <hal_details> 6334 This value should be 4 or less, expect for the high speed recording session, where the 6335 max batch sizes may be larger than 1. 6336 </hal_details> 6337 </entry> 6338 <entry name="partialResultCount" type="int32" visibility="public" optional="true"> 6339 <description>Defines how many sub-components 6340 a result will be composed of. 6341 </description> 6342 <range>&gt;= 1</range> 6343 <details>In order to combat the pipeline latency, partial results 6344 may be delivered to the application layer from the camera device as 6345 soon as they are available. 6346 6347 Optional; defaults to 1. A value of 1 means that partial 6348 results are not supported, and only the final TotalCaptureResult will 6349 be produced by the camera device. 6350 6351 A typical use case for this might be: after requesting an 6352 auto-focus (AF) lock the new AF state might be available 50% 6353 of the way through the pipeline. The camera device could 6354 then immediately dispatch this state via a partial result to 6355 the application, and the rest of the metadata via later 6356 partial results. 6357 </details> 6358 </entry> 6359 <entry name="availableCapabilities" type="byte" visibility="public" 6360 enum="true" container="array" hwlevel="legacy"> 6361 <array> 6362 <size>n</size> 6363 </array> 6364 <enum> 6365 <value>BACKWARD_COMPATIBLE 6366 <notes>The minimal set of capabilities that every camera 6367 device (regardless of android.info.supportedHardwareLevel) 6368 supports. 6369 6370 This capability is listed by all normal devices, and 6371 indicates that the camera device has a feature set 6372 that's comparable to the baseline requirements for the 6373 older android.hardware.Camera API. 6374 6375 Devices with the DEPTH_OUTPUT capability might not list this 6376 capability, indicating that they support only depth measurement, 6377 not standard color output. 6378 </notes> 6379 </value> 6380 <value optional="true">MANUAL_SENSOR 6381 <notes> 6382 The camera device can be manually controlled (3A algorithms such 6383 as auto-exposure, and auto-focus can be bypassed). 6384 The camera device supports basic manual control of the sensor image 6385 acquisition related stages. This means the following controls are 6386 guaranteed to be supported: 6387 6388 * Manual frame duration control 6389 * android.sensor.frameDuration 6390 * android.sensor.info.maxFrameDuration 6391 * Manual exposure control 6392 * android.sensor.exposureTime 6393 * android.sensor.info.exposureTimeRange 6394 * Manual sensitivity control 6395 * android.sensor.sensitivity 6396 * android.sensor.info.sensitivityRange 6397 * Manual lens control (if the lens is adjustable) 6398 * android.lens.* 6399 * Manual flash control (if a flash unit is present) 6400 * android.flash.* 6401 * Manual black level locking 6402 * android.blackLevel.lock 6403 * Auto exposure lock 6404 * android.control.aeLock 6405 6406 If any of the above 3A algorithms are enabled, then the camera 6407 device will accurately report the values applied by 3A in the 6408 result. 6409 6410 A given camera device may also support additional manual sensor controls, 6411 but this capability only covers the above list of controls. 6412 6413 If this is supported, android.scaler.streamConfigurationMap will 6414 additionally return a min frame duration that is greater than 6415 zero for each supported size-format combination. 6416 6417 For camera devices with LOGICAL_MULTI_CAMERA capability, when the underlying active 6418 physical camera switches, exposureTime, sensitivity, and lens properties may change 6419 even if AE/AF is locked. However, the overall auto exposure and auto focus experience 6420 for users will be consistent. Refer to LOGICAL_MULTI_CAMERA capability for details. 6421 </notes> 6422 </value> 6423 <value optional="true">MANUAL_POST_PROCESSING 6424 <notes> 6425 The camera device post-processing stages can be manually controlled. 6426 The camera device supports basic manual control of the image post-processing 6427 stages. This means the following controls are guaranteed to be supported: 6428 6429 * Manual tonemap control 6430 * android.tonemap.curve 6431 * android.tonemap.mode 6432 * android.tonemap.maxCurvePoints 6433 * android.tonemap.gamma 6434 * android.tonemap.presetCurve 6435 6436 * Manual white balance control 6437 * android.colorCorrection.transform 6438 * android.colorCorrection.gains 6439 * Manual lens shading map control 6440 * android.shading.mode 6441 * android.statistics.lensShadingMapMode 6442 * android.statistics.lensShadingMap 6443 * android.lens.info.shadingMapSize 6444 * Manual aberration correction control (if aberration correction is supported) 6445 * android.colorCorrection.aberrationMode 6446 * android.colorCorrection.availableAberrationModes 6447 * Auto white balance lock 6448 * android.control.awbLock 6449 6450 If auto white balance is enabled, then the camera device 6451 will accurately report the values applied by AWB in the result. 6452 6453 A given camera device may also support additional post-processing 6454 controls, but this capability only covers the above list of controls. 6455 6456 For camera devices with LOGICAL_MULTI_CAMERA capability, when underlying active 6457 physical camera switches, tonemap, white balance, and shading map may change even if 6458 awb is locked. However, the overall post-processing experience for users will be 6459 consistent. Refer to LOGICAL_MULTI_CAMERA capability for details. 6460 </notes> 6461 </value> 6462 <value optional="true">RAW 6463 <notes> 6464 The camera device supports outputting RAW buffers and 6465 metadata for interpreting them. 6466 6467 Devices supporting the RAW capability allow both for 6468 saving DNG files, and for direct application processing of 6469 raw sensor images. 6470 6471 * RAW_SENSOR is supported as an output format. 6472 * The maximum available resolution for RAW_SENSOR streams 6473 will match either the value in 6474 android.sensor.info.pixelArraySize or 6475 android.sensor.info.preCorrectionActiveArraySize. 6476 * All DNG-related optional metadata entries are provided 6477 by the camera device. 6478 </notes> 6479 </value> 6480 <value optional="true" visibility="java_public">PRIVATE_REPROCESSING 6481 <notes> 6482 The camera device supports the Zero Shutter Lag reprocessing use case. 6483 6484 * One input stream is supported, that is, `android.request.maxNumInputStreams == 1`. 6485 * {@link android.graphics.ImageFormat#PRIVATE} is supported as an output/input format, 6486 that is, {@link android.graphics.ImageFormat#PRIVATE} is included in the lists of 6487 formats returned by {@link 6488 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats} and {@link 6489 android.hardware.camera2.params.StreamConfigurationMap#getOutputFormats}. 6490 * {@link android.hardware.camera2.params.StreamConfigurationMap#getValidOutputFormatsForInput} 6491 returns non-empty int[] for each supported input format returned by {@link 6492 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. 6493 * Each size returned by {@link 6494 android.hardware.camera2.params.StreamConfigurationMap#getInputSizes 6495 getInputSizes(ImageFormat.PRIVATE)} is also included in {@link 6496 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes 6497 getOutputSizes(ImageFormat.PRIVATE)} 6498 * Using {@link android.graphics.ImageFormat#PRIVATE} does not cause a frame rate drop 6499 relative to the sensor's maximum capture rate (at that resolution). 6500 * {@link android.graphics.ImageFormat#PRIVATE} will be reprocessable into both 6501 {@link android.graphics.ImageFormat#YUV_420_888} and 6502 {@link android.graphics.ImageFormat#JPEG} formats. 6503 * For a MONOCHROME camera supporting Y8 format, {@link 6504 android.graphics.ImageFormat#PRIVATE} will be reprocessable into 6505 {@link android.graphics.ImageFormat#Y8}. 6506 * The maximum available resolution for PRIVATE streams 6507 (both input/output) will match the maximum available 6508 resolution of JPEG streams. 6509 * Static metadata android.reprocess.maxCaptureStall. 6510 * Only below controls are effective for reprocessing requests and 6511 will be present in capture results, other controls in reprocess 6512 requests will be ignored by the camera device. 6513 * android.jpeg.* 6514 * android.noiseReduction.mode 6515 * android.edge.mode 6516 * android.noiseReduction.availableNoiseReductionModes and 6517 android.edge.availableEdgeModes will both list ZERO_SHUTTER_LAG as a supported mode. 6518 </notes> 6519 </value> 6520 <value optional="true">READ_SENSOR_SETTINGS 6521 <notes> 6522 The camera device supports accurately reporting the sensor settings for many of 6523 the sensor controls while the built-in 3A algorithm is running. This allows 6524 reporting of sensor settings even when these settings cannot be manually changed. 6525 6526 The values reported for the following controls are guaranteed to be available 6527 in the CaptureResult, including when 3A is enabled: 6528 6529 * Exposure control 6530 * android.sensor.exposureTime 6531 * Sensitivity control 6532 * android.sensor.sensitivity 6533 * Lens controls (if the lens is adjustable) 6534 * android.lens.focusDistance 6535 * android.lens.aperture 6536 6537 This capability is a subset of the MANUAL_SENSOR control capability, and will 6538 always be included if the MANUAL_SENSOR capability is available. 6539 </notes> 6540 </value> 6541 <value optional="true">BURST_CAPTURE 6542 <notes> 6543 The camera device supports capturing high-resolution images at >= 20 frames per 6544 second, in at least the uncompressed YUV format, when post-processing settings are 6545 set to FAST. Additionally, all image resolutions less than 24 megapixels can be 6546 captured at >= 10 frames per second. Here, 'high resolution' means at least 8 6547 megapixels, or the maximum resolution of the device, whichever is smaller. 6548 </notes> 6549 <sdk_notes> 6550 More specifically, this means that a size matching the camera device's active array 6551 size is listed as a supported size for the {@link 6552 android.graphics.ImageFormat#YUV_420_888} format in either {@link 6553 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} or {@link 6554 android.hardware.camera2.params.StreamConfigurationMap#getHighResolutionOutputSizes}, 6555 with a minimum frame duration for that format and size of either <= 1/20 s, or 6556 <= 1/10 s if the image size is less than 24 megapixels, respectively; and 6557 the android.control.aeAvailableTargetFpsRanges entry lists at least one FPS range 6558 where the minimum FPS is >= 1 / minimumFrameDuration for the maximum-size 6559 YUV_420_888 format. If that maximum size is listed in {@link 6560 android.hardware.camera2.params.StreamConfigurationMap#getHighResolutionOutputSizes}, 6561 then the list of resolutions for YUV_420_888 from {@link 6562 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} contains at 6563 least one resolution >= 8 megapixels, with a minimum frame duration of <= 1/20 6564 s. 6565 6566 If the device supports the {@link 6567 android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10}, {@link 6568 android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12}, {@link 6569 android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8}, then those can also be 6570 captured at the same rate as the maximum-size YUV_420_888 resolution is. 6571 6572 If the device supports the PRIVATE_REPROCESSING capability, then the same guarantees 6573 as for the YUV_420_888 format also apply to the {@link 6574 android.graphics.ImageFormat#PRIVATE} format. 6575 6576 In addition, the android.sync.maxLatency field is guaranteed to have a value between 0 6577 and 4, inclusive. android.control.aeLockAvailable and android.control.awbLockAvailable 6578 are also guaranteed to be `true` so burst capture with these two locks ON yields 6579 consistent image output. 6580 </sdk_notes> 6581 <ndk_notes> 6582 More specifically, this means that at least one output {@link 6583 android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888} size listed in 6584 {@link 6585 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 6586 is larger or equal to the 'high resolution' defined above, and can be captured at at 6587 least 20 fps. For the largest {@link 6588 android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888} size listed in 6589 {@link 6590 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}, 6591 camera device can capture this size for at least 10 frames per second if the size is 6592 less than 24 megapixels. Also the android.control.aeAvailableTargetFpsRanges entry 6593 lists at least one FPS range where the minimum FPS is >= 1 / minimumFrameDuration 6594 for the largest YUV_420_888 size. 6595 6596 If the device supports the {@link 6597 android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10}, {@link 6598 android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12}, {@link 6599 android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8}, then those can also be 6600 captured at the same rate as the maximum-size YUV_420_888 resolution is. 6601 6602 In addition, the android.sync.maxLatency field is guaranteed to have a value between 0 6603 and 4, inclusive. android.control.aeLockAvailable and android.control.awbLockAvailable 6604 are also guaranteed to be `true` so burst capture with these two locks ON yields 6605 consistent image output. 6606 </ndk_notes> 6607 </value> 6608 <value optional="true" visibility="java_public">YUV_REPROCESSING 6609 <notes> 6610 The camera device supports the YUV_420_888 reprocessing use case, similar as 6611 PRIVATE_REPROCESSING, This capability requires the camera device to support the 6612 following: 6613 6614 * One input stream is supported, that is, `android.request.maxNumInputStreams == 1`. 6615 * {@link android.graphics.ImageFormat#YUV_420_888} is supported as an output/input 6616 format, that is, YUV_420_888 is included in the lists of formats returned by {@link 6617 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats} and {@link 6618 android.hardware.camera2.params.StreamConfigurationMap#getOutputFormats}. 6619 * {@link 6620 android.hardware.camera2.params.StreamConfigurationMap#getValidOutputFormatsForInput} 6621 returns non-empty int[] for each supported input format returned by {@link 6622 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. 6623 * Each size returned by {@link 6624 android.hardware.camera2.params.StreamConfigurationMap#getInputSizes 6625 getInputSizes(YUV_420_888)} is also included in {@link 6626 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes 6627 getOutputSizes(YUV_420_888)} 6628 * Using {@link android.graphics.ImageFormat#YUV_420_888} does not cause a frame rate 6629 drop relative to the sensor's maximum capture rate (at that resolution). 6630 * {@link android.graphics.ImageFormat#YUV_420_888} will be reprocessable into both 6631 {@link android.graphics.ImageFormat#YUV_420_888} and {@link 6632 android.graphics.ImageFormat#JPEG} formats. 6633 * The maximum available resolution for {@link 6634 android.graphics.ImageFormat#YUV_420_888} streams (both input/output) will match the 6635 maximum available resolution of {@link android.graphics.ImageFormat#JPEG} streams. 6636 * For a MONOCHROME camera with Y8 format support, all the requirements mentioned 6637 above for YUV_420_888 apply for Y8 format as well. 6638 * Static metadata android.reprocess.maxCaptureStall. 6639 * Only the below controls are effective for reprocessing requests and will be present 6640 in capture results. The reprocess requests are from the original capture results 6641 that are associated with the intermediate {@link 6642 android.graphics.ImageFormat#YUV_420_888} output buffers. All other controls in the 6643 reprocess requests will be ignored by the camera device. 6644 * android.jpeg.* 6645 * android.noiseReduction.mode 6646 * android.edge.mode 6647 * android.reprocess.effectiveExposureFactor 6648 * android.noiseReduction.availableNoiseReductionModes and 6649 android.edge.availableEdgeModes will both list ZERO_SHUTTER_LAG as a supported mode. 6650 </notes> 6651 </value> 6652 <value optional="true">DEPTH_OUTPUT 6653 <notes> 6654 The camera device can produce depth measurements from its field of view. 6655 6656 This capability requires the camera device to support the following: 6657 6658 * {@link android.graphics.ImageFormat#DEPTH16|AIMAGE_FORMAT_DEPTH16} is supported as 6659 an output format. 6660 * {@link 6661 android.graphics.ImageFormat#DEPTH_POINT_CLOUD|AIMAGE_FORMAT_DEPTH_POINT_CLOUD} is 6662 optionally supported as an output format. 6663 * This camera device, and all camera devices with the same android.lens.facing, will 6664 list the following calibration metadata entries in both {@link 6665 android.hardware.camera2.CameraCharacteristics|ACameraManager_getCameraCharacteristics} 6666 and {@link 6667 android.hardware.camera2.CaptureResult|ACameraCaptureSession_captureCallback_result}: 6668 - android.lens.poseTranslation 6669 - android.lens.poseRotation 6670 - android.lens.intrinsicCalibration 6671 - android.lens.distortion 6672 * The android.depth.depthIsExclusive entry is listed by this device. 6673 * As of Android P, the android.lens.poseReference entry is listed by this device. 6674 * A LIMITED camera with only the DEPTH_OUTPUT capability does not have to support 6675 normal YUV_420_888, Y8, JPEG, and PRIV-format outputs. It only has to support the 6676 DEPTH16 format. 6677 6678 Generally, depth output operates at a slower frame rate than standard color capture, 6679 so the DEPTH16 and DEPTH_POINT_CLOUD formats will commonly have a stall duration that 6680 should be accounted for (see {@link 6681 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration|ACAMERA_DEPTH_AVAILABLE_DEPTH_STALL_DURATIONS}). 6682 On a device that supports both depth and color-based output, to enable smooth preview, 6683 using a repeating burst is recommended, where a depth-output target is only included 6684 once every N frames, where N is the ratio between preview output rate and depth output 6685 rate, including depth stall time. 6686 </notes> 6687 </value> 6688 <value optional="true" visibility="java_public">CONSTRAINED_HIGH_SPEED_VIDEO 6689 <notes> 6690 The device supports constrained high speed video recording (frame rate >=120fps) use 6691 case. The camera device will support high speed capture session created by {@link 6692 android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}, which 6693 only accepts high speed request lists created by {@link 6694 android.hardware.camera2.CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList}. 6695 6696 A camera device can still support high speed video streaming by advertising the high 6697 speed FPS ranges in android.control.aeAvailableTargetFpsRanges. For this case, all 6698 normal capture request per frame control and synchronization requirements will apply 6699 to the high speed fps ranges, the same as all other fps ranges. This capability 6700 describes the capability of a specialized operating mode with many limitations (see 6701 below), which is only targeted at high speed video recording. 6702 6703 The supported high speed video sizes and fps ranges are specified in {@link 6704 android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoFpsRanges}. 6705 To get desired output frame rates, the application is only allowed to select video 6706 size and FPS range combinations provided by {@link 6707 android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoSizes}. The 6708 fps range can be controlled via android.control.aeTargetFpsRange. 6709 6710 In this capability, the camera device will override aeMode, awbMode, and afMode to 6711 ON, AUTO, and CONTINUOUS_VIDEO, respectively. All post-processing block mode 6712 controls will be overridden to be FAST. Therefore, no manual control of capture 6713 and post-processing parameters is possible. All other controls operate the 6714 same as when android.control.mode == AUTO. This means that all other 6715 android.control.* fields continue to work, such as 6716 6717 * android.control.aeTargetFpsRange 6718 * android.control.aeExposureCompensation 6719 * android.control.aeLock 6720 * android.control.awbLock 6721 * android.control.effectMode 6722 * android.control.aeRegions 6723 * android.control.afRegions 6724 * android.control.awbRegions 6725 * android.control.afTrigger 6726 * android.control.aePrecaptureTrigger 6727 * android.control.zoomRatio 6728 6729 Outside of android.control.*, the following controls will work: 6730 6731 * android.flash.mode (TORCH mode only, automatic flash for still capture will not 6732 work since aeMode is ON) 6733 * android.lens.opticalStabilizationMode (if it is supported) 6734 * android.scaler.cropRegion 6735 * android.statistics.faceDetectMode (if it is supported) 6736 6737 For high speed recording use case, the actual maximum supported frame rate may 6738 be lower than what camera can output, depending on the destination Surfaces for 6739 the image data. For example, if the destination surface is from video encoder, 6740 the application need check if the video encoder is capable of supporting the 6741 high frame rate for a given video size, or it will end up with lower recording 6742 frame rate. If the destination surface is from preview window, the actual preview frame 6743 rate will be bounded by the screen refresh rate. 6744 6745 The camera device will only support up to 2 high speed simultaneous output surfaces 6746 (preview and recording surfaces) in this mode. Above controls will be effective only 6747 if all of below conditions are true: 6748 6749 * The application creates a camera capture session with no more than 2 surfaces via 6750 {@link 6751 android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}. The 6752 targeted surfaces must be preview surface (either from {@link 6753 android.view.SurfaceView} or {@link android.graphics.SurfaceTexture}) or recording 6754 surface(either from {@link android.media.MediaRecorder#getSurface} or {@link 6755 android.media.MediaCodec#createInputSurface}). 6756 * The stream sizes are selected from the sizes reported by 6757 {@link android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoSizes}. 6758 * The FPS ranges are selected from {@link 6759 android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoFpsRanges}. 6760 6761 When above conditions are NOT satisfied, 6762 {@link android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession} 6763 will fail. 6764 6765 Switching to a FPS range that has different maximum FPS may trigger some camera device 6766 reconfigurations, which may introduce extra latency. It is recommended that 6767 the application avoids unnecessary maximum target FPS changes as much as possible 6768 during high speed streaming. 6769 </notes> 6770 </value> 6771 <value optional="true" hal_version="3.3" >MOTION_TRACKING 6772 <notes> 6773 The camera device supports the MOTION_TRACKING value for 6774 android.control.captureIntent, which limits maximum exposure time to 20 ms. 6775 6776 This limits the motion blur of capture images, resulting in better image tracking 6777 results for use cases such as image stabilization or augmented reality. 6778 </notes> 6779 </value> 6780 <value optional="true" hal_version="3.3">LOGICAL_MULTI_CAMERA 6781 <notes> 6782 The camera device is a logical camera backed by two or more physical cameras. 6783 6784 In API level 28, the physical cameras must also be exposed to the application via 6785 {@link android.hardware.camera2.CameraManager#getCameraIdList}. 6786 6787 Starting from API level 29: 6788 6789 * Some or all physical cameras may not be independently exposed to the application, 6790 in which case the physical camera IDs will not be available in 6791 {@link android.hardware.camera2.CameraManager#getCameraIdList}. But the 6792 application can still query the physical cameras' characteristics by calling 6793 {@link android.hardware.camera2.CameraManager#getCameraCharacteristics}. 6794 * If a physical camera is hidden from camera ID list, the mandatory stream 6795 combinations for that physical camera must be supported through the logical camera 6796 using physical streams. One exception is that in API level 30, a physical camera 6797 may become unavailable via 6798 {@link CameraManager.AvailabilityCallback#onPhysicalCameraUnavailable|ACameraManager_PhysicalCameraAvailabilityCallback} 6799 callback. 6800 6801 Combinations of logical and physical streams, or physical streams from different 6802 physical cameras are not guaranteed. However, if the camera device supports 6803 {@link CameraDevice#isSessionConfigurationSupported|ACameraDevice_isSessionConfigurationSupported}, 6804 application must be able to query whether a stream combination involving physical 6805 streams is supported by calling 6806 {@link CameraDevice#isSessionConfigurationSupported|ACameraDevice_isSessionConfigurationSupported}. 6807 6808 Camera application shouldn't assume that there are at most 1 rear camera and 1 front 6809 camera in the system. For an application that switches between front and back cameras, 6810 the recommendation is to switch between the first rear camera and the first front 6811 camera in the list of supported camera devices. 6812 6813 This capability requires the camera device to support the following: 6814 6815 * The IDs of underlying physical cameras are returned via 6816 {@link android.hardware.camera2.CameraCharacteristics#getPhysicalCameraIds}. 6817 * This camera device must list static metadata 6818 android.logicalMultiCamera.sensorSyncType in 6819 {@link android.hardware.camera2.CameraCharacteristics}. 6820 * The underlying physical cameras' static metadata must list the following entries, 6821 so that the application can correlate pixels from the physical streams: 6822 - android.lens.poseReference 6823 - android.lens.poseRotation 6824 - android.lens.poseTranslation 6825 - android.lens.intrinsicCalibration 6826 - android.lens.distortion 6827 * The SENSOR_INFO_TIMESTAMP_SOURCE of the logical device and physical devices must be 6828 the same. 6829 * The logical camera must be LIMITED or higher device. 6830 6831 A logical camera device's dynamic metadata may contain 6832 android.logicalMultiCamera.activePhysicalId to notify the application of the current 6833 active physical camera Id. An active physical camera is the physical camera from which 6834 the logical camera's main image data outputs (YUV or RAW) and metadata come from. 6835 In addition, this serves as an indication which physical camera is used to output to 6836 a RAW stream, or in case only physical cameras support RAW, which physical RAW stream 6837 the application should request. 6838 6839 Logical camera's static metadata tags below describe the default active physical 6840 camera. An active physical camera is default if it's used when application directly 6841 uses requests built from a template. All templates will default to the same active 6842 physical camera. 6843 6844 - android.sensor.info.sensitivityRange 6845 - android.sensor.info.colorFilterArrangement 6846 - android.sensor.info.exposureTimeRange 6847 - android.sensor.info.maxFrameDuration 6848 - android.sensor.info.physicalSize 6849 - android.sensor.info.whiteLevel 6850 - android.sensor.info.lensShadingApplied 6851 - android.sensor.referenceIlluminant1 6852 - android.sensor.referenceIlluminant2 6853 - android.sensor.calibrationTransform1 6854 - android.sensor.calibrationTransform2 6855 - android.sensor.colorTransform1 6856 - android.sensor.colorTransform2 6857 - android.sensor.forwardMatrix1 6858 - android.sensor.forwardMatrix2 6859 - android.sensor.blackLevelPattern 6860 - android.sensor.maxAnalogSensitivity 6861 - android.sensor.opticalBlackRegions 6862 - android.sensor.availableTestPatternModes 6863 - android.lens.info.hyperfocalDistance 6864 - android.lens.info.minimumFocusDistance 6865 - android.lens.info.focusDistanceCalibration 6866 - android.lens.poseRotation 6867 - android.lens.poseTranslation 6868 - android.lens.intrinsicCalibration 6869 - android.lens.poseReference 6870 - android.lens.distortion 6871 6872 The field of view of non-RAW physical streams must not be smaller than that of the 6873 non-RAW logical streams, or the maximum field-of-view of the physical camera, 6874 whichever is smaller. The application should check the physical capture result 6875 metadata for how the physical streams are cropped or zoomed. More specifically, given 6876 the physical camera result metadata, the effective horizontal field-of-view of the 6877 physical camera is: 6878 6879 fov = 2 * atan2(cropW * sensorW / (2 * zoomRatio * activeArrayW), focalLength) 6880 6881 where the equation parameters are the physical camera's crop region width, physical 6882 sensor width, zoom ratio, active array width, and focal length respectively. Typically 6883 the physical stream of active physical camera has the same field-of-view as the 6884 logical streams. However, the same may not be true for physical streams from 6885 non-active physical cameras. For example, if the logical camera has a wide-ultrawide 6886 configuration where the wide lens is the default, when the crop region is set to the 6887 logical camera's active array size, (and the zoom ratio set to 1.0 starting from 6888 Android 11), a physical stream for the ultrawide camera may prefer outputting images 6889 with larger field-of-view than that of the wide camera for better stereo matching 6890 margin or more robust motion tracking. At the same time, the physical non-RAW streams' 6891 field of view must not be smaller than the requested crop region and zoom ratio, as 6892 long as it's within the physical lens' capability. For example, for a logical camera 6893 with wide-tele lens configuration where the wide lens is the default, if the logical 6894 camera's crop region is set to maximum size, and zoom ratio set to 1.0, the physical 6895 stream for the tele lens will be configured to its maximum size crop region (no zoom). 6896 6897 *Deprecated:* Prior to Android 11, the field of view of all non-RAW physical streams 6898 cannot be larger than that of non-RAW logical streams. If the logical camera has a 6899 wide-ultrawide lens configuration where the wide lens is the default, when the logical 6900 camera's crop region is set to maximum size, the FOV of the physical streams for the 6901 ultrawide lens will be the same as the logical stream, by making the crop region 6902 smaller than its active array size to compensate for the smaller focal length. 6903 6904 For a logical camera, typically the underlying physical cameras have different RAW 6905 capabilities (such as resolution or CFA pattern). There are two ways for the 6906 application to capture RAW images from the logical camera: 6907 6908 * If the logical camera has RAW capability, the application can create and use RAW 6909 streams in the same way as before. In case a RAW stream is configured, to maintain 6910 backward compatibility, the camera device makes sure the default active physical 6911 camera remains active and does not switch to other physical cameras. (One exception 6912 is that, if the logical camera consists of identical image sensors and advertises 6913 multiple focalLength due to different lenses, the camera device may generate RAW 6914 images from different physical cameras based on the focalLength being set by the 6915 application.) This backward-compatible approach usually results in loss of optical 6916 zoom, to telephoto lens or to ultrawide lens. 6917 * Alternatively, if supported by the device, 6918 {@link android.hardware.camera2.MultiResolutionImageReader} 6919 can be used to capture RAW images from one of the underlying physical cameras ( 6920 depending on current zoom level). Because different physical cameras may have 6921 different RAW characteristics, the application needs to use the characteristics 6922 and result metadata of the active physical camera for the relevant RAW metadata. 6923 6924 The capture request and result metadata tags required for backward compatible camera 6925 functionalities will be solely based on the logical camera capability. On the other 6926 hand, the use of manual capture controls (sensor or post-processing) with a 6927 logical camera may result in unexpected behavior when the HAL decides to switch 6928 between physical cameras with different characteristics under the hood. For example, 6929 when the application manually sets exposure time and sensitivity while zooming in, 6930 the brightness of the camera images may suddenly change because HAL switches from one 6931 physical camera to the other. 6932 </notes> 6933 </value> 6934 <value optional="true" hal_version="3.3" >MONOCHROME 6935 <notes> 6936 The camera device is a monochrome camera that doesn't contain a color filter array, 6937 and for YUV_420_888 stream, the pixel values on U and V planes are all 128. 6938 6939 A MONOCHROME camera must support the guaranteed stream combinations required for 6940 its device level and capabilities. Additionally, if the monochrome camera device 6941 supports Y8 format, all mandatory stream combination requirements related to {@link 6942 android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888 YUV_420_888} apply 6943 to {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} as well. There are no 6944 mandatory stream combination requirements with regard to 6945 {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} for Bayer camera devices. 6946 6947 Starting from Android Q, the SENSOR_INFO_COLOR_FILTER_ARRANGEMENT of a MONOCHROME 6948 camera will be either MONO or NIR. 6949 </notes> 6950 </value> 6951 <value optional="true" hal_version="3.4" >SECURE_IMAGE_DATA 6952 <notes> 6953 The camera device is capable of writing image data into a region of memory 6954 inaccessible to Android userspace or the Android kernel, and only accessible to 6955 trusted execution environments (TEE). 6956 </notes> 6957 </value> 6958 <value optional="true" hal_version="3.5" >SYSTEM_CAMERA 6959 <notes> 6960 The camera device is only accessible by Android's system components and privileged 6961 applications. Processes need to have the android.permission.SYSTEM_CAMERA in 6962 addition to android.permission.CAMERA in order to connect to this camera device. 6963 </notes> 6964 </value> 6965 <value optional="true" visibility="java_public" hal_version="3.5">OFFLINE_PROCESSING 6966 <notes> 6967 The camera device supports the OFFLINE_PROCESSING use case. 6968 6969 With OFFLINE_PROCESSING capability, the application can switch an ongoing 6970 capture session to offline mode by calling the 6971 CameraCaptureSession#switchToOffline method and specify streams to be kept in offline 6972 mode. The camera will then stop currently active repeating requests, prepare for 6973 some requests to go into offline mode, and return an offline session object. After 6974 the switchToOffline call returns, the original capture session is in closed state as 6975 if the CameraCaptureSession#close method has been called. 6976 In the offline mode, all inflight requests will continue to be processed in the 6977 background, and the application can immediately close the camera or create a new 6978 capture session without losing those requests' output images and capture results. 6979 6980 While the camera device is processing offline requests, it 6981 might not be able to support all stream configurations it can support 6982 without offline requests. When that happens, the createCaptureSession 6983 method call will fail. The following stream configurations are guaranteed to work 6984 without hitting the resource busy exception: 6985 6986 * One ongoing offline session: target one output surface of YUV or 6987 JPEG format, any resolution. 6988 * The active camera capture session: 6989 1. One preview surface (SurfaceView or SurfaceTexture) up to 1920 width 6990 1. One YUV ImageReader surface up to 1920 width 6991 1. One Jpeg ImageReader, any resolution: the camera device is 6992 allowed to slow down JPEG output speed by 50% if there is any ongoing offline 6993 session. 6994 1. If the device supports PRIVATE_REPROCESSING, one pair of ImageWriter/ImageReader 6995 surfaces of private format, with the same resolution that is larger or equal to 6996 the JPEG ImageReader resolution above. 6997 * Alternatively, the active camera session above can be replaced by an legacy 6998 {@link android.hardware.Camera Camera} with the following parameter settings: 6999 1. Preview size up to 1920 width 7000 1. Preview callback size up to 1920 width 7001 1. Video size up to 1920 width 7002 1. Picture size, any resolution: the camera device is 7003 allowed to slow down JPEG output speed by 50% if there is any ongoing offline 7004 session. 7005 </notes> 7006 </value> 7007 <value optional="true" hal_version="3.6" >ULTRA_HIGH_RESOLUTION_SENSOR 7008 <notes> 7009 This camera device is capable of producing ultra high resolution images in 7010 addition to the image sizes described in the 7011 android.scaler.streamConfigurationMap. 7012 It can operate in 'default' mode and 'max resolution' mode. It generally does this 7013 by binning pixels in 'default' mode and not binning them in 'max resolution' mode. 7014 `android.scaler.streamConfigurationMap` describes the streams supported in 'default' 7015 mode. 7016 The stream configurations supported in 'max resolution' mode are described by 7017 `android.scaler.streamConfigurationMapMaximumResolution`. 7018 The maximum resolution mode pixel array size of a camera device 7019 (`android.sensor.info.pixelArraySize`) with this capability, 7020 will be at least 24 megapixels. 7021 </notes> 7022 </value> 7023 <value optional="true" visibility="java_public" hal_version="3.6">REMOSAIC_REPROCESSING 7024 <notes> 7025 The device supports reprocessing from the `RAW_SENSOR` format with a bayer pattern 7026 given by android.sensor.info.binningFactor (m x n group of pixels with the same 7027 color filter) to a remosaiced regular bayer pattern. 7028 7029 This capability will only be present for devices with 7030 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 7031 capability. When 7032 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 7033 devices do not advertise this capability, 7034 {@link android.graphics.ImageFormat#RAW_SENSOR} images will already have a 7035 regular bayer pattern. 7036 7037 If a `RAW_SENSOR` stream is requested along with another non-RAW stream in a 7038 {@link android.hardware.camera2.CaptureRequest} (if multiple streams are supported 7039 when android.sensor.pixelMode is set to 7040 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}), 7041 the `RAW_SENSOR` stream will have a regular bayer pattern. 7042 7043 This capability requires the camera device to support the following : 7044 7045 * The {@link android.hardware.camera2.params.StreamConfigurationMap} mentioned below 7046 refers to the one, described by 7047 `android.scaler.streamConfigurationMapMaximumResolution`. 7048 * One input stream is supported, that is, `android.request.maxNumInputStreams == 1`. 7049 * {@link android.graphics.ImageFormat#RAW_SENSOR} is supported as an output/input 7050 format, that is, {@link android.graphics.ImageFormat#RAW_SENSOR} is included in the 7051 lists of formats returned by {@link 7052 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats} and {@link 7053 android.hardware.camera2.params.StreamConfigurationMap#getOutputFormats}. 7054 * {@link android.hardware.camera2.params.StreamConfigurationMap#getValidOutputFormatsForInput} 7055 returns non-empty int[] for each supported input format returned by {@link 7056 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. 7057 * Each size returned by {@link 7058 android.hardware.camera2.params.StreamConfigurationMap#getInputSizes 7059 getInputSizes(ImageFormat.RAW_SENSOR)} is also included in {@link 7060 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes 7061 getOutputSizes(ImageFormat.RAW_SENSOR)} 7062 * Using {@link android.graphics.ImageFormat#RAW_SENSOR} does not cause a frame rate 7063 drop relative to the sensor's maximum capture rate (at that resolution). 7064 * No CaptureRequest controls will be applicable when a request has an input target 7065 with {@link android.graphics.ImageFormat#RAW_SENSOR} format. 7066 </notes> 7067 </value> 7068 <value optional="true" visibility="java_public" hal_version="3.8">DYNAMIC_RANGE_TEN_BIT 7069 <notes> 7070 The device supports one or more 10-bit camera outputs according to the dynamic range 7071 profiles specified in 7072 {@link android.hardware.camera2.params.DynamicRangeProfiles#getSupportedProfiles}. 7073 They can be configured as part of the capture session initialization via 7074 {@link android.hardware.camera2.params.OutputConfiguration#setDynamicRangeProfile}. 7075 Cameras that enable this capability must also support the following: 7076 7077 * Profile {@link android.hardware.camera2.params.DynamicRangeProfiles#HLG10} 7078 * All mandatory stream combinations for this specific capability as per 7079 [documentation](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#10-bit-output-additional-guaranteed-configurations) 7080 * In case the device is not able to capture some combination of supported 7081 standard 8-bit and/or 10-bit dynamic range profiles within the same capture request, 7082 then those constraints must be listed in 7083 {@link android.hardware.camera2.params.DynamicRangeProfiles#getProfileCaptureRequestConstraints} 7084 * Recommended dynamic range profile listed in 7085 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_RECOMMENDED_TEN_BIT_DYNAMIC_RANGE_PROFILE}. 7086 </notes> 7087 </value> 7088 <value optional="true" hal_version="3.8">STREAM_USE_CASE 7089 <notes> 7090 The camera device supports selecting a per-stream use case via 7091 {@link android.hardware.camera2.params.OutputConfiguration#setStreamUseCase} 7092 so that the device can optimize camera pipeline parameters such as tuning, sensor 7093 mode, or ISP settings for a specific user scenario. 7094 Some sample usages of this capability are: 7095 7096 * Distinguish high quality YUV captures from a regular YUV stream where 7097 the image quality may not be as good as the JPEG stream, or 7098 * Use one stream to serve multiple purposes: viewfinder, video recording and 7099 still capture. This is common with applications that wish to apply edits equally 7100 to preview, saved images, and saved videos. 7101 7102 This capability requires the camera device to support the following 7103 stream use cases: 7104 7105 * DEFAULT for backward compatibility where the application doesn't set 7106 a stream use case 7107 * PREVIEW for live viewfinder and in-app image analysis 7108 * STILL_CAPTURE for still photo capture 7109 * VIDEO_RECORD for recording video clips 7110 * PREVIEW_VIDEO_STILL for one single stream used for viewfinder, video 7111 recording, and still capture. 7112 * VIDEO_CALL for long running video calls 7113 7114 {@link android.hardware.camera2.CameraCharacteristics#SCALER_AVAILABLE_STREAM_USE_CASES} 7115 lists all of the supported stream use cases. 7116 7117 Refer to the 7118 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#stream-use-case-capability-additional-guaranteed-configurations) 7119 for the mandatory stream combinations involving stream use cases, which can also be 7120 queried via {@link android.hardware.camera2.params.MandatoryStreamCombination}. 7121 </notes> 7122 </value> 7123 <value optional="true" visibility="java_public" hal_version="3.9">COLOR_SPACE_PROFILES 7124 <notes> 7125 The device supports querying the possible combinations of color spaces, image 7126 formats, and dynamic range profiles supported by the camera and requesting a 7127 particular color space for a session via 7128 {@link android.hardware.camera2.params.SessionConfiguration#setColorSpace}. 7129 7130 Cameras that enable this capability may or may not also implement dynamic range 7131 profiles. If they don't, 7132 {@link android.hardware.camera2.params.ColorSpaceProfiles#getSupportedDynamicRangeProfiles} 7133 will return only 7134 {@link android.hardware.camera2.params.DynamicRangeProfiles#STANDARD} and 7135 {@link android.hardware.camera2.params.ColorSpaceProfiles#getSupportedColorSpacesForDynamicRange} 7136 will assume support of the 7137 {@link android.hardware.camera2.params.DynamicRangeProfiles#STANDARD} 7138 profile in all combinations of color spaces and image formats. 7139 </notes> 7140 </value> 7141 </enum> 7142 <description>List of capabilities that this camera device 7143 advertises as fully supporting.</description> 7144 <details> 7145 A capability is a contract that the camera device makes in order 7146 to be able to satisfy one or more use cases. 7147 7148 Listing a capability guarantees that the whole set of features 7149 required to support a common use will all be available. 7150 7151 Using a subset of the functionality provided by an unsupported 7152 capability may be possible on a specific camera device implementation; 7153 to do this query each of android.request.availableRequestKeys, 7154 android.request.availableResultKeys, 7155 android.request.availableCharacteristicsKeys. 7156 7157 The following capabilities are guaranteed to be available on 7158 android.info.supportedHardwareLevel `==` FULL devices: 7159 7160 * MANUAL_SENSOR 7161 * MANUAL_POST_PROCESSING 7162 7163 Other capabilities may be available on either FULL or LIMITED 7164 devices, but the application should query this key to be sure. 7165 </details> 7166 <hal_details> 7167 Additional constraint details per-capability will be available 7168 in the Compatibility Test Suite. 7169 7170 Minimum baseline requirements required for the 7171 BACKWARD_COMPATIBLE capability are not explicitly listed. 7172 Instead refer to "BC" tags and the camera CTS tests in the 7173 android.hardware.camera2.cts package. 7174 7175 Listed controls that can be either request or result (e.g. 7176 android.sensor.exposureTime) must be available both in the 7177 request and the result in order to be considered to be 7178 capability-compliant. 7179 7180 For example, if the HAL claims to support MANUAL control, 7181 then exposure time must be configurable via the request _and_ 7182 the actual exposure applied must be available via 7183 the result. 7184 7185 If MANUAL_SENSOR is omitted, the HAL may choose to omit the 7186 android.scaler.availableMinFrameDurations static property entirely. 7187 7188 For PRIVATE_REPROCESSING and YUV_REPROCESSING capabilities, see 7189 hardware/libhardware/include/hardware/camera3.h Section 10 for more information. 7190 7191 Devices that support the MANUAL_SENSOR capability must support the 7192 CAMERA3_TEMPLATE_MANUAL template defined in camera3.h. 7193 7194 Devices that support the PRIVATE_REPROCESSING capability or the 7195 YUV_REPROCESSING capability must support the 7196 CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template defined in camera3.h. 7197 7198 For DEPTH_OUTPUT, the depth-format keys 7199 android.depth.availableDepthStreamConfigurations, 7200 android.depth.availableDepthMinFrameDurations, 7201 android.depth.availableDepthStallDurations must be available, in 7202 addition to the other keys explicitly mentioned in the DEPTH_OUTPUT 7203 enum notes. The entry android.depth.maxDepthSamples must be available 7204 if the DEPTH_POINT_CLOUD format is supported (HAL pixel format BLOB, dataspace 7205 DEPTH). 7206 7207 For a camera device with LOGICAL_MULTI_CAMERA capability, it should operate in the 7208 same way as a physical camera device based on its hardware level and capabilities. 7209 It's recommended that its feature set is superset of that of individual physical cameras. 7210 7211 * In camera1 API, to maintain application compatibility, for each camera facing, there 7212 may be one or more {logical_camera_id, physical_camera_1_id, physical_camera_2_id, ...} 7213 combinations, where logical_camera_id is composed of physical_camera_N_id, camera 7214 framework will only advertise one camera id 7215 (within the combinations for the particular facing) that is frontmost in the HAL 7216 published camera id list. 7217 For example, if HAL advertises 6 back facing camera IDs (ID0 to ID5), among which ID4 7218 and ID5 are logical cameras backed by ID0+ID1 and ID2+ID3 respectively. In this case, 7219 only ID0 will be available for camera1 API to use. 7220 7221 * Camera HAL is strongly recommended to advertise camera devices with best feature, 7222 power, performance, and latency tradeoffs at the front of the camera id list. 7223 7224 * Camera HAL may switch between physical cameras depending on focalLength, cropRegion, or 7225 zoomRatio. If physical cameras have different sizes, HAL must maintain a single logical 7226 camera activeArraySize/pixelArraySize/preCorrectionActiveArraySize, and must do proper 7227 mapping between logical camera and underlying physical cameras for all related metadata 7228 tags, such as crop region, zoomRatio, 3A regions, and intrinsicCalibration. 7229 7230 * Starting from HIDL ICameraDevice version 3.5, camera HAL must support 7231 isStreamCombinationSupported for application to query whether a particular logical and 7232 physical streams combination are supported. 7233 7234 A MONOCHROME camera device must also advertise BACKWARD_COMPATIBLE capability, and must 7235 not advertise MANUAL_POST_PROCESSING capability. 7236 7237 * To maintain backward compatibility, the camera device must support all 7238 BACKWARD_COMPATIBLE required keys. The android.control.awbAvailableModes key only contains 7239 AUTO, and android.control.awbState are either CONVERGED or LOCKED depending on 7240 android.control.awbLock. 7241 7242 * android.colorCorrection.mode, android.colorCorrection.transform, and 7243 android.colorCorrection.gains must not be in available request and result keys. 7244 As a result, the camera device cannot be a FULL device. However, the HAL can 7245 still advertise other individual capabilities. 7246 7247 * If the device supports tonemap control, only android.tonemap.curveRed is used. 7248 CurveGreen and curveBlue are no-ops. 7249 7250 In Android API level 28, a MONOCHROME camera device must not have RAW capability. From 7251 API level 29, a camera is allowed to have both MONOCHROME and RAW capabilities. 7252 7253 To support the legacy API to ICameraDevice 3.x shim layer, devices advertising 7254 OFFLINE_PROCESSING capability must also support configuring an input stream of the same 7255 size as the picture size if: 7256 7257 * The device supports PRIVATE_REPROCESSING capability 7258 * The device's maximal JPEG resolution can reach 30 FPS min frame duration 7259 * The device does not support HAL based ZSL (android.control.enableZsl) 7260 7261 For devices which support SYSTEM_CAMERA and LOGICAL_MULTI_CAMERA capabilities: 7262 7263 Hidden physical camera ids[1] must not be be shared[2] between public camera devices 7264 and camera devices advertising SYSTEM_CAMERA capability. 7265 7266 [1] - Camera device ids which are advertised in the 7267 ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS list, and not available through 7268 ICameraProvider.getCameraIdList(). 7269 7270 [2] - The ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS lists, must not have common 7271 camera ids. 7272 </hal_details> 7273 </entry> 7274 <entry name="availableRequestKeys" type="int32" visibility="ndk_public" 7275 container="array" hwlevel="legacy"> 7276 <array> 7277 <size>n</size> 7278 </array> 7279 <description>A list of all keys that the camera device has available 7280 to use with {@link android.hardware.camera2.CaptureRequest|ACaptureRequest}.</description> 7281 7282 <details>Attempting to set a key into a CaptureRequest that is not 7283 listed here will result in an invalid request and will be rejected 7284 by the camera device. 7285 7286 This field can be used to query the feature set of a camera device 7287 at a more granular level than capabilities. This is especially 7288 important for optional keys that are not listed under any capability 7289 in android.request.availableCapabilities. 7290 </details> 7291 <hal_details> 7292 Vendor tags can be listed here. Vendor tag metadata should also 7293 use the extensions C api (refer to camera3.h for more details). 7294 7295 Setting/getting vendor tags will be checked against the metadata 7296 vendor extensions API and not against this field. 7297 7298 The HAL must not consume any request tags that are not listed either 7299 here or in the vendor tag list. 7300 7301 The public camera2 API will always make the vendor tags visible 7302 via 7303 {@link android.hardware.camera2.CameraCharacteristics#getAvailableCaptureRequestKeys}. 7304 </hal_details> 7305 </entry> 7306 <entry name="availableResultKeys" type="int32" visibility="ndk_public" 7307 container="array" hwlevel="legacy"> 7308 <array> 7309 <size>n</size> 7310 </array> 7311 <description>A list of all keys that the camera device has available to use with {@link 7312 android.hardware.camera2.CaptureResult|ACameraCaptureSession_captureCallback_result}. 7313 </description> 7314 7315 <details>Attempting to get a key from a CaptureResult that is not 7316 listed here will always return a `null` value. Getting a key from 7317 a CaptureResult that is listed here will generally never return a `null` 7318 value. 7319 7320 The following keys may return `null` unless they are enabled: 7321 7322 * android.statistics.lensShadingMap (non-null iff android.statistics.lensShadingMapMode == ON) 7323 7324 (Those sometimes-null keys will nevertheless be listed here 7325 if they are available.) 7326 7327 This field can be used to query the feature set of a camera device 7328 at a more granular level than capabilities. This is especially 7329 important for optional keys that are not listed under any capability 7330 in android.request.availableCapabilities. 7331 </details> 7332 <hal_details> 7333 Tags listed here must always have an entry in the result metadata, 7334 even if that size is 0 elements. Only array-type tags (e.g. lists, 7335 matrices, strings) are allowed to have 0 elements. 7336 7337 Vendor tags can be listed here. Vendor tag metadata should also 7338 use the extensions C api (refer to camera3.h for more details). 7339 7340 Setting/getting vendor tags will be checked against the metadata 7341 vendor extensions API and not against this field. 7342 7343 The HAL must not produce any result tags that are not listed either 7344 here or in the vendor tag list. 7345 7346 The public camera2 API will always make the vendor tags visible via {@link 7347 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys}. 7348 </hal_details> 7349 </entry> 7350 <entry name="availableCharacteristicsKeys" type="int32" visibility="ndk_public" 7351 container="array" hwlevel="legacy"> 7352 <array> 7353 <size>n</size> 7354 </array> 7355 <description>A list of all keys that the camera device has available to use with {@link 7356 android.hardware.camera2.CameraCharacteristics|ACameraManager_getCameraCharacteristics}. 7357 </description> 7358 <details>This entry follows the same rules as 7359 android.request.availableResultKeys (except that it applies for 7360 CameraCharacteristics instead of CaptureResult). See above for more 7361 details. 7362 </details> 7363 <hal_details> 7364 Keys listed here must always have an entry in the static info metadata, 7365 even if that size is 0 elements. Only array-type tags (e.g. lists, 7366 matrices, strings) are allowed to have 0 elements. 7367 7368 Vendor tags can listed here. Vendor tag metadata should also use 7369 the extensions C api (refer to camera3.h for more details). 7370 7371 Setting/getting vendor tags will be checked against the metadata 7372 vendor extensions API and not against this field. 7373 7374 The HAL must not have any tags in its static info that are not listed 7375 either here or in the vendor tag list. 7376 7377 The public camera2 API will always make the vendor tags visible 7378 via {@link android.hardware.camera2.CameraCharacteristics#getKeys}. 7379 </hal_details> 7380 </entry> 7381 <entry name="availableSessionKeys" type="int32" visibility="ndk_public" 7382 container="array" hwlevel="legacy" hal_version="3.3"> 7383 <array> 7384 <size>n</size> 7385 </array> 7386 <description>A subset of the available request keys that the camera device 7387 can pass as part of the capture session initialization.</description> 7388 7389 <details> This is a subset of android.request.availableRequestKeys which 7390 contains a list of keys that are difficult to apply per-frame and 7391 can result in unexpected delays when modified during the capture session 7392 lifetime. Typical examples include parameters that require a 7393 time-consuming hardware re-configuration or internal camera pipeline 7394 change. For performance reasons we advise clients to pass their initial 7395 values as part of 7396 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 7397 Once the camera capture session is enabled it is also recommended to avoid 7398 changing them from their initial values set in 7399 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 7400 Control over session parameters can still be exerted in capture requests 7401 but clients should be aware and expect delays during their application. 7402 An example usage scenario could look like this: 7403 7404 * The camera client starts by querying the session parameter key list via 7405 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys|ACameraManager_getCameraCharacteristics}. 7406 * Before triggering the capture session create sequence, a capture request 7407 must be built via 7408 {@link CameraDevice#createCaptureRequest|ACameraDevice_createCaptureRequest} 7409 using an appropriate template matching the particular use case. 7410 * The client should go over the list of session parameters and check 7411 whether some of the keys listed matches with the parameters that 7412 they intend to modify as part of the first capture request. 7413 * If there is no such match, the capture request can be passed 7414 unmodified to 7415 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 7416 * If matches do exist, the client should update the respective values 7417 and pass the request to 7418 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 7419 * After the capture session initialization completes the session parameter 7420 key list can continue to serve as reference when posting or updating 7421 further requests. As mentioned above further changes to session 7422 parameters should ideally be avoided, if updates are necessary 7423 however clients could expect a delay/glitch during the 7424 parameter switch. 7425 7426 </details> 7427 <hal_details> 7428 If android.control.aeTargetFpsRange is part of the session parameters and constrained high 7429 speed mode is enabled, then only modifications of the maximum framerate value will be 7430 monitored by the framework and can trigger camera re-configuration. For more information 7431 about framerate ranges during constrained high speed sessions see 7432 {@link android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}. 7433 Vendor tags can be listed here. Vendor tag metadata should also 7434 use the extensions C api (refer to 7435 android.hardware.camera.device.V3_4.StreamConfiguration.sessionParams for more details). 7436 7437 Setting/getting vendor tags will be checked against the metadata 7438 vendor extensions API and not against this field. 7439 7440 The HAL must not consume any request tags in the session parameters that 7441 are not listed either here or in the vendor tag list. 7442 7443 The public camera2 API will always make the vendor tags visible 7444 via 7445 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys}. 7446 </hal_details> 7447 </entry> 7448 <entry name="availablePhysicalCameraRequestKeys" type="int32" visibility="ndk_public" 7449 container="array" hwlevel="limited" hal_version="3.3"> 7450 <array> 7451 <size>n</size> 7452 </array> 7453 <description>A subset of the available request keys that can be overridden for 7454 physical devices backing a logical multi-camera.</description> 7455 <details> 7456 This is a subset of android.request.availableRequestKeys which contains a list 7457 of keys that can be overridden using 7458 {@link android.hardware.camera2.CaptureRequest.Builder#setPhysicalCameraKey}. 7459 The respective value of such request key can be obtained by calling 7460 {@link android.hardware.camera2.CaptureRequest.Builder#getPhysicalCameraKey}. 7461 Capture requests that contain individual physical device requests must be built via 7462 {@link android.hardware.camera2.CameraDevice#createCaptureRequest(int, Set)}. 7463 </details> 7464 <hal_details> 7465 Vendor tags can be listed here. Vendor tag metadata should also 7466 use the extensions C api (refer to 7467 android.hardware.camera.device.V3_4.CaptureRequest.physicalCameraSettings for more 7468 details). 7469 7470 Setting/getting vendor tags will be checked against the metadata 7471 vendor extensions API and not against this field. 7472 7473 The HAL must not consume any request tags in the session parameters that 7474 are not listed either here or in the vendor tag list. 7475 7476 There should be no overlap between this set of keys and the available session keys 7477 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys} along 7478 with any other controls that can have impact on the dual-camera sync. 7479 7480 The public camera2 API will always make the vendor tags visible 7481 via 7482 {@link android.hardware.camera2.CameraCharacteristics#getAvailablePhysicalCameraRequestKeys}. 7483 </hal_details> 7484 </entry> 7485 <entry name="characteristicKeysNeedingPermission" type="int32" visibility="hidden" 7486 container="array" hwlevel="legacy" hal_version="3.4"> 7487 <array> 7488 <size>n</size> 7489 </array> 7490 <description>A list of camera characteristics keys that are only available 7491 in case the camera client has camera permission.</description> 7492 7493 <details>The entry contains a subset of 7494 {@link android.hardware.camera2.CameraCharacteristics#getKeys} that require camera clients 7495 to acquire the {@link android.Manifest.permission#CAMERA} permission before calling 7496 {@link android.hardware.camera2.CameraManager#getCameraCharacteristics}. If the 7497 permission is not held by the camera client, then the values of the respective properties 7498 will not be present in {@link android.hardware.camera2.CameraCharacteristics}. 7499 </details> 7500 <hal_details> 7501 Do not set this property directly, camera service will overwrite any previous values. 7502 </hal_details> 7503 </entry> 7504 <entry name="availableDynamicRangeProfiles" type="int32" visibility="java_public" 7505 synthetic="true" optional="true" typedef="dynamicRangeProfiles"> 7506 <description>Devices supporting the 10-bit output capability 7507 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7508 must list their supported dynamic range profiles along with capture request 7509 constraints for specific profile combinations. 7510 </description> 7511 <details> 7512 Camera clients can retrieve the list of supported 10-bit dynamic range profiles by calling 7513 {@link android.hardware.camera2.params.DynamicRangeProfiles#getSupportedProfiles}. 7514 Any of them can be configured by setting OutputConfiguration dynamic range profile in 7515 {@link android.hardware.camera2.params.OutputConfiguration#setDynamicRangeProfile}. 7516 Clients can also check if there are any constraints that limit the combination 7517 of supported profiles that can be referenced within a single capture request by calling 7518 {@link android.hardware.camera2.params.DynamicRangeProfiles#getProfileCaptureRequestConstraints}. 7519 </details> 7520 </entry> 7521 <entry name="availableDynamicRangeProfilesMap" type="int64" visibility="ndk_public" 7522 optional="true" enum="true" container="array" hal_version="3.8"> 7523 <array> 7524 <size>n</size> 7525 <size>3</size> 7526 </array> 7527 <enum> 7528 <value id="0x1">STANDARD 7529 <notes> 7530 8-bit SDR profile which is the default for all non 10-bit output capable devices. 7531 </notes> 7532 </value> 7533 <value id="0x2">HLG10 7534 <notes> 7535 10-bit pixel samples encoded using the Hybrid log-gamma transfer function. 7536 </notes> 7537 </value> 7538 <value id="0x4">HDR10 7539 <notes> 7540 10-bit pixel samples encoded using the SMPTE ST 2084 transfer function. 7541 This profile utilizes internal static metadata to increase the quality 7542 of the capture. 7543 </notes> 7544 </value> 7545 <value id="0x8">HDR10_PLUS 7546 <notes> 7547 10-bit pixel samples encoded using the SMPTE ST 2084 transfer function. 7548 In contrast to HDR10, this profile uses internal per-frame metadata 7549 to further enhance the quality of the capture. 7550 </notes> 7551 </value> 7552 <value id="0x10">DOLBY_VISION_10B_HDR_REF 7553 <notes> 7554 This is a camera mode for Dolby Vision capture optimized for a more scene 7555 accurate capture. This would typically differ from what a specific device 7556 might want to tune for a consumer optimized Dolby Vision general capture. 7557 </notes> 7558 </value> 7559 <value id="0x20">DOLBY_VISION_10B_HDR_REF_PO 7560 <notes> 7561 This is the power optimized mode for 10-bit Dolby Vision HDR Reference Mode. 7562 </notes> 7563 </value> 7564 <value id="0x40">DOLBY_VISION_10B_HDR_OEM 7565 <notes> 7566 This is the camera mode for the default Dolby Vision capture mode for the 7567 specific device. This would be tuned by each specific device for consumer 7568 pleasing results that resonate with their particular audience. We expect 7569 that each specific device would have a different look for their default 7570 Dolby Vision capture. 7571 </notes> 7572 </value> 7573 <value id="0x80">DOLBY_VISION_10B_HDR_OEM_PO 7574 <notes> 7575 This is the power optimized mode for 10-bit Dolby Vision HDR device specific 7576 capture Mode. 7577 </notes> 7578 </value> 7579 <value id="0x100">DOLBY_VISION_8B_HDR_REF 7580 <notes> 7581 This is the 8-bit version of the Dolby Vision reference capture mode optimized 7582 for scene accuracy. 7583 </notes> 7584 </value> 7585 <value id="0x200">DOLBY_VISION_8B_HDR_REF_PO 7586 <notes> 7587 This is the power optimized mode for 8-bit Dolby Vision HDR Reference Mode. 7588 </notes> 7589 </value> 7590 <value id="0x400">DOLBY_VISION_8B_HDR_OEM 7591 <notes> 7592 This is the 8-bit version of device specific tuned and optimized Dolby Vision 7593 capture mode. 7594 </notes> 7595 </value> 7596 <value id="0x800">DOLBY_VISION_8B_HDR_OEM_PO 7597 <notes> 7598 This is the power optimized mode for 8-bit Dolby Vision HDR device specific 7599 capture Mode. 7600 </notes> 7601 </value> 7602 <value id="0x1000">MAX 7603 <notes> 7604 </notes> 7605 </value> 7606 </enum> 7607 <description>A map of all available 10-bit dynamic range profiles along with their 7608 capture request constraints. 7609 </description> 7610 <details>Devices supporting the 10-bit output capability 7611 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7612 must list their supported dynamic range profiles. In case the camera is not able to 7613 support every possible profile combination within a single capture request, then the 7614 constraints must be listed here as well. 7615 </details> 7616 <hal_details> 7617 The array contains three entries per supported profile: 7618 1) The supported dynamic profile value. Do note that 7619 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_STANDARD is assumed to be always 7620 present and must not be listed. 7621 2) A bitmap combination of all supported profiles that can be referenced at the same 7622 time within a single capture request. Do note that a value of 0 means that there are 7623 no constraints and all combinations are supported. 7624 3) A flag indicating the presence of an internal lookahead functionality that 7625 can increase the streaming latency by more than 3 buffers. The value 0 will indicate 7626 that latency doesn't exceed 3 buffers, everything different than 0 will indicate 7627 latency that is beyond 3 buffers. In case the flag is set, then Camera clients will be 7628 advised to avoid configuring this profile for camera latency sensitive outputs such as 7629 preview. Do note, that such extra latency must not be present for the HLG10 profile. 7630 7631 For example if we assume that a device exists that can only support HLG10, HDR10 and 7632 HDR10_PLUS from the possible 10-bit profiles with the following capture constraints: 7633 1) HLG10 can be included in any capture request without constraints. 7634 2) HDR10 and HDR10_PLUS can only be referenced together and/or with HLG10 but not with 7635 STANDARD. 7636 In the same example, HLG10 and HDR10 will not have additional lookahead latency, and 7637 HDR10+ will have latency that exceeds 3 buffers. 7638 The resulting array should look like this: 7639 [ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HLG10, 0, 0, 7640 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10, 7641 (ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10 | 7642 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HLG10 | 7643 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10_PLUS), 0, 7644 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10_PLUS, 7645 (ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10_PLUS | 7646 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HLG10 | 7647 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10), 1] 7648 7649 Camera providers must ensure that each processed buffer from a stream configured with the 7650 HDR10 dynamic range profile includes SMPTE ST 2086 static metadata by calling 7651 'android::hardware::graphics::mapper::V4_0::IMapper::set' before returning the buffer. 7652 7653 Camera providers must ensure that each processed buffer from a stream configured 7654 with HDR10_PLUS dynamic range profile includes SMPTE ST 2094-40 dynamic 7655 metadata by calling 'android::hardware::graphics::mapper::V4_0::IMapper::set' before 7656 returning the buffer. 7657 7658 Camera providers must ensure that each processed buffer from a stream configured 7659 with any of the 10-bit Dolby Vision dynamic range profiles includes SMPTE ST 2094-10 7660 dynamic metadata by calling 'android::hardware::graphics::mapper::V4_0::IMapper::set' 7661 before returning the buffer. 7662 </hal_details> 7663 </entry> 7664 <entry name="recommendedTenBitDynamicRangeProfile" type="int64" visibility="java_public" 7665 optional="true" hal_version="3.8"> 7666 <description>Recommended 10-bit dynamic range profile.</description> 7667 <details>Devices supporting the 10-bit output capability 7668 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7669 must list a 10-bit supported dynamic range profile that is expected to perform 7670 optimally in terms of image quality, power and performance. 7671 The value advertised can be used as a hint by camera clients when configuring the dynamic 7672 range profile when calling 7673 {@link android.hardware.camera2.params.OutputConfiguration#setDynamicRangeProfile}. 7674 </details> 7675 </entry> 7676 <entry name="availableColorSpaceProfiles" type="int32" visibility="java_public" 7677 synthetic="true" optional="true" typedef="colorSpaceProfiles" hal_version="3.9"> 7678 <description> 7679 An interface for querying the color space profiles supported by a camera device. 7680 </description> 7681 <details> 7682 A color space profile is a combination of a color space, an image format, and a dynamic 7683 range profile. Camera clients can retrieve the list of supported color spaces by calling 7684 {@link android.hardware.camera2.params.ColorSpaceProfiles#getSupportedColorSpaces} or 7685 {@link android.hardware.camera2.params.ColorSpaceProfiles#getSupportedColorSpacesForDynamicRange}. 7686 If a camera does not support the 7687 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7688 capability, the dynamic range profile will always be 7689 {@link android.hardware.camera2.params.DynamicRangeProfiles#STANDARD}. Color space 7690 capabilities are queried in combination with an {@link android.graphics.ImageFormat}. 7691 If a camera client wants to know the general color space capabilities of a camera device 7692 regardless of image format, it can specify {@link android.graphics.ImageFormat#UNKNOWN}. 7693 The color space for a session can be configured by setting the SessionConfiguration 7694 color space via {@link android.hardware.camera2.params.SessionConfiguration#setColorSpace}. 7695 </details> 7696 </entry> 7697 <entry name="availableColorSpaceProfilesMap" type="int64" visibility="ndk_public" 7698 optional="true" enum="true" container="array" hal_version="3.9"> 7699 <array> 7700 <size>n</size> 7701 <size>3</size> 7702 </array> 7703 <enum> 7704 <value id="-1">UNSPECIFIED 7705 <notes> 7706 Default value, when not explicitly specified. The Camera device will choose the color 7707 space to employ. 7708 </notes> 7709 </value> 7710 <value visibility="system" id="0">SRGB 7711 <notes> 7712 RGB color space sRGB standardized as IEC 61966-2.1:1999. 7713 </notes> 7714 </value> 7715 <value visibility="system" id="7">DISPLAY_P3 7716 <notes> 7717 RGB color space Display P3 based on SMPTE RP 431-2-2007 and IEC 61966-2.1:1999. 7718 </notes> 7719 </value> 7720 <value visibility="system" id="16">BT2020_HLG 7721 <notes> 7722 RGB color space BT.2100 standardized as Hybrid Log Gamma encoding. 7723 </notes> 7724 </value> 7725 </enum> 7726 <description> 7727 A list of all possible color space profiles supported by a camera device. 7728 </description> 7729 <details> 7730 A color space profile is a combination of a color space, an image format, and a dynamic range 7731 profile. If a camera does not support the 7732 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7733 capability, the dynamic range profile will always be 7734 {@link android.hardware.camera2.params.DynamicRangeProfiles#STANDARD}. Camera clients can 7735 use {@link android.hardware.camera2.params.SessionConfiguration#setColorSpace} to select 7736 a color space. 7737 </details> 7738 <hal_details> 7739 The array contains three entries per supported profile: 7740 7741 1) The supported color space. 7742 2) An image format which can be used with this color space. 7743 3) A bitmap of all compatible dynamic range profiles, if the device is HDR-capable. 7744 7745 The possible values for #1 are the positive values of the 7746 ANDROID_REQUEST_AVAILABLE_COLOR_SPACE_PROFILES_MAP_* enum, which is equivalent to 7747 {@link android.graphics.ColorSpace.Named} and its ordinals. UNSPECIFIED should not be 7748 used here. It should be noted that not all {@link android.graphics.ColorSpace.Named} 7749 values are supported, only those in the 7750 ANDROID_REQUEST_AVAILABLE_COLOR_SPACE_PROFILES_MAP_* enum. 7751 7752 The possible values for #2 consist of the public-facing image/pixel formats, found at 7753 {@link android.graphics.ImageFormat} and {@link android.graphics.PixelFormat}. Each map 7754 to a HAL pixel format except for {@link android.graphics.ImageFormat.JPEG}, 7755 {@link android.graphics.ImageFormat.HEIC}, and 7756 {@link android.graphics.ImageFormat.DEPTH_JPEG}. Depth formats besides DEPTH_JPEG are 7757 not applicable and should not be specified. If there are no constraints on the type of 7758 image format a color space is compatible with, this can be 7759 {@link android.graphics.ImageFormat.UNKNOWN}. 7760 7761 If the device is not HDR-capable, #3 should always be 7762 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_STANDARD. Otherwise, #3 should be a 7763 bitmap of the compatible ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_* values. 7764 </hal_details> 7765 </entry> 7766 </static> 7767 </section> 7768 <section name="scaler"> 7769 <controls> 7770 <entry name="cropRegion" type="int32" visibility="public" 7771 container="array" typedef="rectangle" hwlevel="legacy"> 7772 <array> 7773 <size>4</size> 7774 </array> 7775 <description>The desired region of the sensor to read out for this capture.</description> 7776 <units>Pixel coordinates relative to 7777 android.sensor.info.activeArraySize or 7778 android.sensor.info.preCorrectionActiveArraySize depending on distortion correction 7779 capability and mode</units> 7780 <details> 7781 This control can be used to implement digital zoom. 7782 7783 For devices not supporting android.distortionCorrection.mode control, the coordinate 7784 system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being 7785 the top-left pixel of the active array. 7786 7787 For devices supporting android.distortionCorrection.mode control, the coordinate system 7788 depends on the mode being set. When the distortion correction mode is OFF, the 7789 coordinate system follows android.sensor.info.preCorrectionActiveArraySize, with `(0, 7790 0)` being the top-left pixel of the pre-correction active array. When the distortion 7791 correction mode is not OFF, the coordinate system follows 7792 android.sensor.info.activeArraySize, with `(0, 0)` being the top-left pixel of the 7793 active array. 7794 7795 Output streams use this rectangle to produce their output, cropping to a smaller region 7796 if necessary to maintain the stream's aspect ratio, then scaling the sensor input to 7797 match the output's configured resolution. 7798 7799 The crop region is usually applied after the RAW to other color space (e.g. YUV) 7800 conversion. As a result RAW streams are not croppable unless supported by the 7801 camera device. See android.scaler.availableStreamUseCases#CROPPED_RAW for details. 7802 7803 For non-raw streams, any additional per-stream cropping will be done to maximize the 7804 final pixel area of the stream. 7805 7806 For example, if the crop region is set to a 4:3 aspect ratio, then 4:3 streams will use 7807 the exact crop region. 16:9 streams will further crop vertically (letterbox). 7808 7809 Conversely, if the crop region is set to a 16:9, then 4:3 outputs will crop horizontally 7810 (pillarbox), and 16:9 streams will match exactly. These additional crops will be 7811 centered within the crop region. 7812 7813 To illustrate, here are several scenarios of different crop regions and output streams, 7814 for a hypothetical camera device with an active array of size `(2000,1500)`. Note that 7815 several of these examples use non-centered crop regions for ease of illustration; such 7816 regions are only supported on devices with FREEFORM capability 7817 (android.scaler.croppingType `== FREEFORM`), but this does not affect the way the crop 7818 rules work otherwise. 7819 7820 * Camera Configuration: 7821 * Active array size: `2000x1500` (3 MP, 4:3 aspect ratio) 7822 * Output stream #1: `640x480` (VGA, 4:3 aspect ratio) 7823 * Output stream #2: `1280x720` (720p, 16:9 aspect ratio) 7824 * Case #1: 4:3 crop region with 2x digital zoom 7825 * Crop region: `Rect(500, 375, 1500, 1125) // (left, top, right, bottom)` 7826 *  7827 * `640x480` stream source area: `(500, 375, 1500, 1125)` (equal to crop region) 7828 * `1280x720` stream source area: `(500, 469, 1500, 1031)` (letterboxed) 7829 * Case #2: 16:9 crop region with ~1.5x digital zoom. 7830 * Crop region: `Rect(500, 375, 1833, 1125)` 7831 *  7832 * `640x480` stream source area: `(666, 375, 1666, 1125)` (pillarboxed) 7833 * `1280x720` stream source area: `(500, 375, 1833, 1125)` (equal to crop region) 7834 * Case #3: 1:1 crop region with ~2.6x digital zoom. 7835 * Crop region: `Rect(500, 375, 1250, 1125)` 7836 *  7837 * `640x480` stream source area: `(500, 469, 1250, 1031)` (letterboxed) 7838 * `1280x720` stream source area: `(500, 543, 1250, 957)` (letterboxed) 7839 * Case #4: Replace `640x480` stream with `1024x1024` stream, with 4:3 crop region: 7840 * Crop region: `Rect(500, 375, 1500, 1125)` 7841 *  7842 * `1024x1024` stream source area: `(625, 375, 1375, 1125)` (pillarboxed) 7843 * `1280x720` stream source area: `(500, 469, 1500, 1031)` (letterboxed) 7844 * Note that in this case, neither of the two outputs is a subset of the other, with 7845 each containing image data the other doesn't have. 7846 7847 If the coordinate system is android.sensor.info.activeArraySize, the width and height 7848 of the crop region cannot be set to be smaller than 7849 `floor( activeArraySize.width / android.scaler.availableMaxDigitalZoom )` and 7850 `floor( activeArraySize.height / android.scaler.availableMaxDigitalZoom )`, respectively. 7851 7852 If the coordinate system is android.sensor.info.preCorrectionActiveArraySize, the width 7853 and height of the crop region cannot be set to be smaller than 7854 `floor( preCorrectionActiveArraySize.width / android.scaler.availableMaxDigitalZoom )` 7855 and 7856 `floor( preCorrectionActiveArraySize.height / android.scaler.availableMaxDigitalZoom )`, 7857 respectively. 7858 7859 The camera device may adjust the crop region to account for rounding and other hardware 7860 requirements; the final crop region used will be included in the output capture result. 7861 7862 The camera sensor output aspect ratio depends on factors such as output stream 7863 combination and android.control.aeTargetFpsRange, and shouldn't be adjusted by using 7864 this control. And the camera device will treat different camera sensor output sizes 7865 (potentially with in-sensor crop) as the same crop of 7866 android.sensor.info.activeArraySize. As a result, the application shouldn't assume the 7867 maximum crop region always maps to the same aspect ratio or field of view for the 7868 sensor output. 7869 7870 Starting from API level 30, it's strongly recommended to use android.control.zoomRatio 7871 to take advantage of better support for zoom with logical multi-camera. The benefits 7872 include better precision with optical-digital zoom combination, and ability to do 7873 zoom-out from 1.0x. When using android.control.zoomRatio for zoom, the crop region in 7874 the capture request should be left as the default activeArray size. The 7875 coordinate system is post-zoom, meaning that the activeArraySize or 7876 preCorrectionActiveArraySize covers the camera device's field of view "after" zoom. See 7877 android.control.zoomRatio for details. 7878 7879 For camera devices with the 7880 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 7881 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 7882 lists android.sensor.pixelMode, 7883 android.sensor.info.activeArraySizeMaximumResolution / 7884 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 7885 coordinate system for requests where android.sensor.pixelMode is set to 7886 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 7887 </details> 7888 <ndk_details> 7889 The data representation is int[4], which maps to (left, top, width, height). 7890 </ndk_details> 7891 <hal_details> 7892 The output streams must maintain square pixels at all 7893 times, no matter what the relative aspect ratios of the 7894 crop region and the stream are. Negative values for 7895 corner are allowed for raw output if full pixel array is 7896 larger than active pixel array. Width and height may be 7897 rounded to nearest larger supportable width, especially 7898 for raw output, where only a few fixed scales may be 7899 possible. 7900 7901 If android.control.zoomRatio is supported by the HAL, the HAL must report the zoom 7902 ratio via android.control.zoomRatio, and change the coordinate system such that 7903 android.sensor.info.preCorrectionActiveArraySize or android.sensor.info.activeArraySize 7904 (depending on whether android.distortionCorrection.mode is supported) is used to 7905 represent the camera field-of-view after zoom. see android.control.zoomRatio for 7906 details. 7907 7908 HAL2.x uses only (x, y, width) 7909 </hal_details> 7910 <tag id="BC" /> 7911 </entry> 7912 </controls> 7913 <static> 7914 <entry name="availableFormats" type="int32" 7915 visibility="hidden" deprecated="true" enum="true" 7916 container="array" typedef="imageFormat"> 7917 <array> 7918 <size>n</size> 7919 </array> 7920 <enum> 7921 <value optional="true" id="0x20">RAW16 7922 <notes> 7923 RAW16 is a standard, cross-platform format for raw image 7924 buffers with 16-bit pixels. 7925 7926 Buffers of this format are typically expected to have a 7927 Color Filter Array (CFA) layout, which is given in 7928 android.sensor.info.colorFilterArrangement. Sensors with 7929 CFAs that are not representable by a format in 7930 android.sensor.info.colorFilterArrangement should not 7931 use this format. 7932 7933 Buffers of this format will also follow the constraints given for 7934 RAW_OPAQUE buffers, but with relaxed performance constraints. 7935 7936 This format is intended to give users access to the full contents 7937 of the buffers coming directly from the image sensor prior to any 7938 cropping or scaling operations, and all coordinate systems for 7939 metadata used for this format are relative to the size of the 7940 active region of the image sensor before any geometric distortion 7941 correction has been applied (i.e. 7942 android.sensor.info.preCorrectionActiveArraySize). Supported 7943 dimensions for this format are limited to the full dimensions of 7944 the sensor (e.g. either android.sensor.info.pixelArraySize or 7945 android.sensor.info.preCorrectionActiveArraySize will be the 7946 only supported output size). 7947 7948 See android.scaler.availableInputOutputFormatsMap for 7949 the full set of performance guarantees. 7950 </notes> 7951 </value> 7952 <value optional="true" id="0x24">RAW_OPAQUE 7953 <notes> 7954 RAW_OPAQUE (or 7955 {@link android.graphics.ImageFormat#RAW_PRIVATE RAW_PRIVATE} 7956 as referred in public API) is a format for raw image buffers 7957 coming from an image sensor. 7958 7959 The actual structure of buffers of this format is 7960 platform-specific, but must follow several constraints: 7961 7962 1. No image post-processing operations may have been applied to 7963 buffers of this type. These buffers contain raw image data coming 7964 directly from the image sensor. 7965 1. If a buffer of this format is passed to the camera device for 7966 reprocessing, the resulting images will be identical to the images 7967 produced if the buffer had come directly from the sensor and was 7968 processed with the same settings. 7969 7970 The intended use for this format is to allow access to the native 7971 raw format buffers coming directly from the camera sensor without 7972 any additional conversions or decrease in framerate. 7973 7974 See android.scaler.availableInputOutputFormatsMap for the full set of 7975 performance guarantees. 7976 </notes> 7977 </value> 7978 <value optional="true" id="0x32315659">YV12 7979 <notes>YCrCb 4:2:0 Planar</notes> 7980 </value> 7981 <value optional="true" id="0x11">YCrCb_420_SP 7982 <notes>NV21</notes> 7983 </value> 7984 <value id="0x22">IMPLEMENTATION_DEFINED 7985 <notes>System internal format, not application-accessible</notes> 7986 </value> 7987 <value id="0x23">YCbCr_420_888 7988 <notes>Flexible YUV420 Format</notes> 7989 </value> 7990 <value id="0x21">BLOB 7991 <notes>JPEG format</notes> 7992 </value> 7993 <value id="0x25" hal_version="3.4">RAW10 7994 <notes>RAW10</notes> 7995 </value> 7996 <value id="0x26" hal_version="3.4">RAW12 7997 <notes>RAW12</notes> 7998 </value> 7999 <value id="0x20203859" hal_version="3.4">Y8 8000 <notes>Y8</notes> 8001 </value> 8002 </enum> 8003 <description>The list of image formats that are supported by this 8004 camera device for output streams.</description> 8005 <deprecation_description> 8006 Not used in HALv3 or newer 8007 </deprecation_description> 8008 <details> 8009 All camera devices will support JPEG and YUV_420_888 formats. 8010 8011 When set to YUV_420_888, application can access the YUV420 data directly. 8012 </details> 8013 <hal_details> 8014 These format values are from HAL_PIXEL_FORMAT_* in 8015 system/core/libsystem/include/system/graphics-base.h. 8016 8017 When IMPLEMENTATION_DEFINED is used, the platform 8018 gralloc module will select a format based on the usage flags provided 8019 by the camera HAL device and the other endpoint of the stream. It is 8020 usually used by preview and recording streams, where the application doesn't 8021 need access the image data. 8022 8023 YCbCr_420_888 format must be supported by the HAL. When an image stream 8024 needs CPU/application direct access, this format will be used. For a MONOCHROME 8025 camera device, the pixel value of Cb and Cr planes is 128. 8026 8027 The BLOB format must be supported by the HAL. This is used for the JPEG stream. 8028 8029 A RAW_OPAQUE buffer should contain only pixel data. It is strongly 8030 recommended that any information used by the camera device when 8031 processing images is fully expressed by the result metadata 8032 for that image buffer. 8033 </hal_details> 8034 <tag id="BC" /> 8035 </entry> 8036 <entry name="availableJpegMinDurations" type="int64" visibility="hidden" deprecated="true" 8037 container="array"> 8038 <array> 8039 <size>n</size> 8040 </array> 8041 <description>The minimum frame duration that is supported 8042 for each resolution in android.scaler.availableJpegSizes. 8043 </description> 8044 <deprecation_description> 8045 Not used in HALv3 or newer 8046 </deprecation_description> 8047 <units>Nanoseconds</units> 8048 <range>TODO: Remove property.</range> 8049 <details> 8050 This corresponds to the minimum steady-state frame duration when only 8051 that JPEG stream is active and captured in a burst, with all 8052 processing (typically in android.*.mode) set to FAST. 8053 8054 When multiple streams are configured, the minimum 8055 frame duration will be &gt;= max(individual stream min 8056 durations)</details> 8057 <tag id="BC" /> 8058 </entry> 8059 <entry name="availableJpegSizes" type="int32" visibility="hidden" 8060 deprecated="true" container="array" typedef="size"> 8061 <array> 8062 <size>n</size> 8063 <size>2</size> 8064 </array> 8065 <description>The JPEG resolutions that are supported by this camera device.</description> 8066 <deprecation_description> 8067 Not used in HALv3 or newer 8068 </deprecation_description> 8069 <range>TODO: Remove property.</range> 8070 <details> 8071 The resolutions are listed as `(width, height)` pairs. All camera devices will support 8072 sensor maximum resolution (defined by android.sensor.info.activeArraySize). 8073 </details> 8074 <hal_details> 8075 The HAL must include sensor maximum resolution 8076 (defined by android.sensor.info.activeArraySize), 8077 and should include half/quarter of sensor maximum resolution. 8078 </hal_details> 8079 <tag id="BC" /> 8080 </entry> 8081 <entry name="availableMaxDigitalZoom" type="float" visibility="public" 8082 hwlevel="legacy" session_characteristics_key_since="35"> 8083 <description>The maximum ratio between both active area width 8084 and crop region width, and active area height and 8085 crop region height, for android.scaler.cropRegion. 8086 </description> 8087 <units>Zoom scale factor</units> 8088 <range>&gt;=1</range> 8089 <details> 8090 This represents the maximum amount of zooming possible by 8091 the camera device, or equivalently, the minimum cropping 8092 window size. 8093 8094 Crop regions that have a width or height that is smaller 8095 than this ratio allows will be rounded up to the minimum 8096 allowed size by the camera device. 8097 8098 Starting from API level 30, when using android.control.zoomRatio to zoom in or out, 8099 the application must use android.control.zoomRatioRange to query both the minimum and 8100 maximum zoom ratio. 8101 </details> 8102 <hal_details> 8103 If the HAL supports android.control.zoomRatio, this value must be equal to or less than 8104 the maximum supported zoomRatio specified in android.control.zoomRatioRange. 8105 </hal_details> 8106 <tag id="BC" /> 8107 </entry> 8108 <entry name="availableProcessedMinDurations" type="int64" visibility="hidden" deprecated="true" 8109 container="array"> 8110 <array> 8111 <size>n</size> 8112 </array> 8113 <description>For each available processed output size (defined in 8114 android.scaler.availableProcessedSizes), this property lists the 8115 minimum supportable frame duration for that size. 8116 </description> 8117 <deprecation_description> 8118 Not used in HALv3 or newer 8119 </deprecation_description> 8120 <units>Nanoseconds</units> 8121 <details> 8122 This should correspond to the frame duration when only that processed 8123 stream is active, with all processing (typically in android.*.mode) 8124 set to FAST. 8125 8126 When multiple streams are configured, the minimum frame duration will 8127 be &gt;= max(individual stream min durations). 8128 </details> 8129 <tag id="BC" /> 8130 </entry> 8131 <entry name="availableProcessedSizes" type="int32" visibility="hidden" 8132 deprecated="true" container="array" typedef="size"> 8133 <array> 8134 <size>n</size> 8135 <size>2</size> 8136 </array> 8137 <description>The resolutions available for use with 8138 processed output streams, such as YV12, NV12, and 8139 platform opaque YUV/RGB streams to the GPU or video 8140 encoders.</description> 8141 <deprecation_description> 8142 Not used in HALv3 or newer 8143 </deprecation_description> 8144 <details> 8145 The resolutions are listed as `(width, height)` pairs. 8146 8147 For a given use case, the actual maximum supported resolution 8148 may be lower than what is listed here, depending on the destination 8149 Surface for the image data. For example, for recording video, 8150 the video encoder chosen may have a maximum size limit (e.g. 1080p) 8151 smaller than what the camera (e.g. maximum resolution is 3264x2448) 8152 can provide. 8153 8154 Please reference the documentation for the image data destination to 8155 check if it limits the maximum size for image data. 8156 </details> 8157 <hal_details> 8158 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 8159 the HAL must include all JPEG sizes listed in android.scaler.availableJpegSizes 8160 and each below resolution if it is smaller than or equal to the sensor 8161 maximum resolution (if they are not listed in JPEG sizes already): 8162 8163 * 240p (320 x 240) 8164 * 480p (640 x 480) 8165 * 720p (1280 x 720) 8166 * 1080p (1920 x 1080) 8167 8168 For LIMITED capability devices (`android.info.supportedHardwareLevel == LIMITED`), 8169 the HAL only has to list up to the maximum video size supported by the devices. 8170 </hal_details> 8171 <tag id="BC" /> 8172 </entry> 8173 <entry name="availableRawMinDurations" type="int64" deprecated="true" 8174 container="array"> 8175 <array> 8176 <size>n</size> 8177 </array> 8178 <description> 8179 For each available raw output size (defined in 8180 android.scaler.availableRawSizes), this property lists the minimum 8181 supportable frame duration for that size. 8182 </description> 8183 <deprecation_description> 8184 Not used in HALv3 or newer 8185 </deprecation_description> 8186 <units>Nanoseconds</units> 8187 <details> 8188 Should correspond to the frame duration when only the raw stream is 8189 active. 8190 8191 When multiple streams are configured, the minimum 8192 frame duration will be &gt;= max(individual stream min 8193 durations)</details> 8194 <tag id="BC" /> 8195 </entry> 8196 <entry name="availableRawSizes" type="int32" deprecated="true" 8197 container="array" typedef="size"> 8198 <array> 8199 <size>n</size> 8200 <size>2</size> 8201 </array> 8202 <description>The resolutions available for use with raw 8203 sensor output streams, listed as width, 8204 height</description> 8205 <deprecation_description> 8206 Not used in HALv3 or newer 8207 </deprecation_description> 8208 </entry> 8209 </static> 8210 <dynamic> 8211 <clone entry="android.scaler.cropRegion" kind="controls"> 8212 </clone> 8213 </dynamic> 8214 <static> 8215 <entry name="availableInputOutputFormatsMap" type="int32" visibility="hidden" 8216 typedef="reprocessFormatsMap"> 8217 <description>The mapping of image formats that are supported by this 8218 camera device for input streams, to their corresponding output formats. 8219 </description> 8220 <details> 8221 All camera devices with at least 1 8222 android.request.maxNumInputStreams will have at least one 8223 available input format. 8224 8225 The camera device will support the following map of formats, 8226 if its dependent capability (android.request.availableCapabilities) is supported: 8227 8228 Input Format | Output Format | Capability 8229 :-------------------------------------------------|:--------------------------------------------------|:---------- 8230 {@link android.graphics.ImageFormat#PRIVATE} | {@link android.graphics.ImageFormat#JPEG} | PRIVATE_REPROCESSING 8231 {@link android.graphics.ImageFormat#PRIVATE} | {@link android.graphics.ImageFormat#YUV_420_888} | PRIVATE_REPROCESSING 8232 {@link android.graphics.ImageFormat#YUV_420_888} | {@link android.graphics.ImageFormat#JPEG} | YUV_REPROCESSING 8233 {@link android.graphics.ImageFormat#YUV_420_888} | {@link android.graphics.ImageFormat#YUV_420_888} | YUV_REPROCESSING 8234 8235 PRIVATE refers to a device-internal format that is not directly application-visible. A 8236 PRIVATE input surface can be acquired by {@link android.media.ImageReader#newInstance} 8237 with {@link android.graphics.ImageFormat#PRIVATE} as the format. 8238 8239 For a PRIVATE_REPROCESSING-capable camera device, using the PRIVATE format as either input 8240 or output will never hurt maximum frame rate (i.e. {@link 8241 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration 8242 getOutputStallDuration(ImageFormat.PRIVATE, size)} is always 0), 8243 8244 Attempting to configure an input stream with output streams not 8245 listed as available in this map is not valid. 8246 8247 Additionally, if the camera device is MONOCHROME with Y8 support, it will also support 8248 the following map of formats if its dependent capability 8249 (android.request.availableCapabilities) is supported: 8250 8251 Input Format | Output Format | Capability 8252 :-------------------------------------------------|:--------------------------------------------------|:---------- 8253 {@link android.graphics.ImageFormat#PRIVATE} | {@link android.graphics.ImageFormat#Y8} | PRIVATE_REPROCESSING 8254 {@link android.graphics.ImageFormat#Y8} | {@link android.graphics.ImageFormat#JPEG} | YUV_REPROCESSING 8255 {@link android.graphics.ImageFormat#Y8} | {@link android.graphics.ImageFormat#Y8} | YUV_REPROCESSING 8256 8257 </details> 8258 <hal_details> 8259 For the formats, see `system/core/libsystem/include/system/graphics-base.h` for a 8260 definition of the image format enumerations. The PRIVATE format refers to the 8261 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED format. The HAL could determine 8262 the actual format by using the gralloc usage flags. 8263 For ZSL use case in particular, the HAL could choose appropriate format (partially 8264 processed YUV or RAW based format) by checking the format and GRALLOC_USAGE_HW_CAMERA_ZSL. 8265 See camera3.h for more details. 8266 8267 This value is encoded as a variable-size array-of-arrays. 8268 The inner array always contains `[format, length, ...]` where 8269 `...` has `length` elements. An inner array is followed by another 8270 inner array if the total metadata entry size hasn't yet been exceeded. 8271 8272 A code sample to read/write this encoding (with a device that 8273 supports reprocessing IMPLEMENTATION_DEFINED to YUV_420_888, and JPEG, 8274 and reprocessing YUV_420_888 to YUV_420_888 and JPEG): 8275 8276 // reading 8277 int32_t* contents = &entry.i32[0]; 8278 for (size_t i = 0; i < entry.count; ) { 8279 int32_t format = contents[i++]; 8280 int32_t length = contents[i++]; 8281 int32_t output_formats[length]; 8282 memcpy(&output_formats[0], &contents[i], 8283 length * sizeof(int32_t)); 8284 i += length; 8285 } 8286 8287 // writing (static example, PRIVATE_REPROCESSING + YUV_REPROCESSING) 8288 int32_t[] contents = { 8289 IMPLEMENTATION_DEFINED, 2, YUV_420_888, BLOB, 8290 YUV_420_888, 2, YUV_420_888, BLOB, 8291 }; 8292 update_camera_metadata_entry(metadata, index, &contents[0], 8293 sizeof(contents)/sizeof(contents[0]), &updated_entry); 8294 8295 If the HAL claims to support any of the capabilities listed in the 8296 above details, then it must also support all the input-output 8297 combinations listed for that capability. It can optionally support 8298 additional formats if it so chooses. 8299 </hal_details> 8300 <tag id="REPROC" /> 8301 </entry> 8302 <entry name="availableStreamConfigurations" type="int32" visibility="ndk_public" 8303 enum="true" container="array" typedef="streamConfiguration" hwlevel="legacy"> 8304 <array> 8305 <size>n</size> 8306 <size>4</size> 8307 </array> 8308 <enum> 8309 <value>OUTPUT</value> 8310 <value>INPUT</value> 8311 </enum> 8312 <description>The available stream configurations that this 8313 camera device supports 8314 (i.e. format, width, height, output/input stream). 8315 </description> 8316 <details> 8317 The configurations are listed as `(format, width, height, input?)` 8318 tuples. 8319 8320 For a given use case, the actual maximum supported resolution 8321 may be lower than what is listed here, depending on the destination 8322 Surface for the image data. For example, for recording video, 8323 the video encoder chosen may have a maximum size limit (e.g. 1080p) 8324 smaller than what the camera (e.g. maximum resolution is 3264x2448) 8325 can provide. 8326 8327 Please reference the documentation for the image data destination to 8328 check if it limits the maximum size for image data. 8329 8330 Not all output formats may be supported in a configuration with 8331 an input stream of a particular format. For more details, see 8332 android.scaler.availableInputOutputFormatsMap. 8333 8334 For applications targeting SDK version older than 31, the following table 8335 describes the minimum required output stream configurations based on the hardware level 8336 (android.info.supportedHardwareLevel): 8337 8338 Format | Size | Hardware Level | Notes 8339 :-------------:|:--------------------------------------------:|:--------------:|:--------------: 8340 JPEG | android.sensor.info.activeArraySize | Any | 8341 JPEG | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 8342 JPEG | 1280x720 (720) | Any | if 720p <= activeArraySize 8343 JPEG | 640x480 (480p) | Any | if 480p <= activeArraySize 8344 JPEG | 320x240 (240p) | Any | if 240p <= activeArraySize 8345 YUV_420_888 | all output sizes available for JPEG | FULL | 8346 YUV_420_888 | all output sizes available for JPEG, up to the maximum video size | LIMITED | 8347 IMPLEMENTATION_DEFINED | same as YUV_420_888 | Any | 8348 8349 For applications targeting SDK version 31 or newer, if the mobile device declares to be 8350 media performance class 12 or higher by setting 8351 {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 8352 the primary camera devices (first rear/front camera in the camera ID list) will not 8353 support JPEG sizes smaller than 1080p. If the application configures a JPEG stream 8354 smaller than 1080p, the camera device will round up the JPEG image size to at least 8355 1080p. The requirements for IMPLEMENTATION_DEFINED and YUV_420_888 stay the same. 8356 This new minimum required output stream configurations are illustrated by the table below: 8357 8358 Format | Size | Hardware Level | Notes 8359 :-------------:|:--------------------------------------------:|:--------------:|:--------------: 8360 JPEG | android.sensor.info.activeArraySize | Any | 8361 JPEG | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 8362 YUV_420_888 | android.sensor.info.activeArraySize | FULL | 8363 YUV_420_888 | 1920x1080 (1080p) | FULL | if 1080p <= activeArraySize 8364 YUV_420_888 | 1280x720 (720) | FULL | if 720p <= activeArraySize 8365 YUV_420_888 | 640x480 (480p) | FULL | if 480p <= activeArraySize 8366 YUV_420_888 | 320x240 (240p) | FULL | if 240p <= activeArraySize 8367 YUV_420_888 | all output sizes available for FULL hardware level, up to the maximum video size | LIMITED | 8368 IMPLEMENTATION_DEFINED | same as YUV_420_888 | Any | 8369 8370 For applications targeting SDK version 31 or newer, if the mobile device doesn't declare 8371 to be media performance class 12 or better by setting 8372 {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 8373 or if the camera device isn't a primary rear/front camera, the minimum required output 8374 stream configurations are the same as for applications targeting SDK version older than 8375 31. 8376 8377 Refer to android.request.availableCapabilities for additional 8378 mandatory stream configurations on a per-capability basis. 8379 8380 Exception on 176x144 (QCIF) resolution: camera devices usually have a fixed capability for 8381 downscaling from larger resolution to smaller, and the QCIF resolution sometimes is not 8382 fully supported due to this limitation on devices with high-resolution image sensors. 8383 Therefore, trying to configure a QCIF resolution stream together with any other 8384 stream larger than 1920x1080 resolution (either width or height) might not be supported, 8385 and capture session creation will fail if it is not. 8386 8387 </details> 8388 <hal_details> 8389 It is recommended (but not mandatory) to also include half/quarter 8390 of sensor maximum resolution for JPEG formats (regardless of hardware 8391 level). 8392 8393 (The following is a rewording of the above required table): 8394 8395 For JPEG format, the sizes may be restricted by below conditions: 8396 8397 * The HAL may choose the aspect ratio of each Jpeg size to be one of well known ones 8398 (e.g. 4:3, 16:9, 3:2 etc.). If the sensor maximum resolution 8399 (defined by android.sensor.info.activeArraySize) has an aspect ratio other than these, 8400 it does not have to be included in the supported JPEG sizes. 8401 * Some hardware JPEG encoders may have pixel boundary alignment requirements, such as 8402 the dimensions being a multiple of 16. 8403 8404 Therefore, the maximum JPEG size may be smaller than sensor maximum resolution. 8405 However, the largest JPEG size must be as close as possible to the sensor maximum 8406 resolution given above constraints. It is required that after aspect ratio adjustments, 8407 additional size reduction due to other issues must be less than 3% in area. For example, 8408 if the sensor maximum resolution is 3280x2464, if the maximum JPEG size has aspect 8409 ratio 4:3, the JPEG encoder alignment requirement is 16, the maximum JPEG size will be 8410 3264x2448. 8411 8412 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 8413 the HAL must include all YUV_420_888 sizes that have JPEG sizes listed 8414 here as output streams. 8415 8416 It must also include each below resolution if it is smaller than or 8417 equal to the sensor maximum resolution (for both YUV_420_888 and JPEG 8418 formats), as output streams: 8419 8420 * 240p (320 x 240) 8421 * 480p (640 x 480) 8422 * 720p (1280 x 720) 8423 * 1080p (1920 x 1080) 8424 8425 Note that for primary cameras (first rear/front facing camera in the camera ID list) 8426 on a device with {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} set to 8427 31 or larger, camera framework filters out JPEG sizes smaller than 1080p depending on 8428 applications' targetSdkLevel. The camera HAL must still support the smaller JPEG sizes 8429 to maintain backward compatibility. 8430 8431 For LIMITED capability devices 8432 (`android.info.supportedHardwareLevel == LIMITED`), 8433 the HAL only has to list up to the maximum video size 8434 supported by the device. 8435 8436 Regardless of hardware level, every output resolution available for 8437 YUV_420_888 must also be available for IMPLEMENTATION_DEFINED. 8438 8439 This supersedes the following fields, which are now deprecated: 8440 8441 * availableFormats 8442 * available[Processed,Raw,Jpeg]Sizes 8443 </hal_details> 8444 </entry> 8445 <entry name="availableMinFrameDurations" type="int64" visibility="ndk_public" 8446 container="array" typedef="streamConfigurationDuration" hwlevel="legacy"> 8447 <array> 8448 <size>4</size> 8449 <size>n</size> 8450 </array> 8451 <description>This lists the minimum frame duration for each 8452 format/size combination. 8453 </description> 8454 <units>(format, width, height, ns) x n</units> 8455 <details> 8456 This should correspond to the frame duration when only that 8457 stream is active, with all processing (typically in android.*.mode) 8458 set to either OFF or FAST. 8459 8460 When multiple streams are used in a request, the minimum frame 8461 duration will be max(individual stream min durations). 8462 8463 See android.sensor.frameDuration and 8464 android.scaler.availableStallDurations for more details about 8465 calculating the max frame rate. 8466 </details> 8467 <tag id="V1" /> 8468 </entry> 8469 <entry name="availableStallDurations" type="int64" visibility="ndk_public" 8470 container="array" typedef="streamConfigurationDuration" hwlevel="legacy"> 8471 <array> 8472 <size>4</size> 8473 <size>n</size> 8474 </array> 8475 <description>This lists the maximum stall duration for each 8476 output format/size combination. 8477 </description> 8478 <units>(format, width, height, ns) x n</units> 8479 <details> 8480 A stall duration is how much extra time would get added 8481 to the normal minimum frame duration for a repeating request 8482 that has streams with non-zero stall. 8483 8484 For example, consider JPEG captures which have the following 8485 characteristics: 8486 8487 * JPEG streams act like processed YUV streams in requests for which 8488 they are not included; in requests in which they are directly 8489 referenced, they act as JPEG streams. This is because supporting a 8490 JPEG stream requires the underlying YUV data to always be ready for 8491 use by a JPEG encoder, but the encoder will only be used (and impact 8492 frame duration) on requests that actually reference a JPEG stream. 8493 * The JPEG processor can run concurrently to the rest of the camera 8494 pipeline, but cannot process more than 1 capture at a time. 8495 8496 In other words, using a repeating YUV request would result 8497 in a steady frame rate (let's say it's 30 FPS). If a single 8498 JPEG request is submitted periodically, the frame rate will stay 8499 at 30 FPS (as long as we wait for the previous JPEG to return each 8500 time). If we try to submit a repeating YUV + JPEG request, then 8501 the frame rate will drop from 30 FPS. 8502 8503 In general, submitting a new request with a non-0 stall time 8504 stream will _not_ cause a frame rate drop unless there are still 8505 outstanding buffers for that stream from previous requests. 8506 8507 Submitting a repeating request with streams (call this `S`) 8508 is the same as setting the minimum frame duration from 8509 the normal minimum frame duration corresponding to `S`, added with 8510 the maximum stall duration for `S`. 8511 8512 If interleaving requests with and without a stall duration, 8513 a request will stall by the maximum of the remaining times 8514 for each can-stall stream with outstanding buffers. 8515 8516 This means that a stalling request will not have an exposure start 8517 until the stall has completed. 8518 8519 This should correspond to the stall duration when only that stream is 8520 active, with all processing (typically in android.*.mode) set to FAST 8521 or OFF. Setting any of the processing modes to HIGH_QUALITY 8522 effectively results in an indeterminate stall duration for all 8523 streams in a request (the regular stall calculation rules are 8524 ignored). 8525 8526 The following formats may always have a stall duration: 8527 8528 * {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG} 8529 * {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16} 8530 8531 The following formats will never have a stall duration: 8532 8533 * {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888} 8534 * {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10} 8535 * {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12} 8536 * {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8} 8537 8538 All other formats may or may not have an allowed stall duration on 8539 a per-capability basis; refer to android.request.availableCapabilities 8540 for more details. 8541 8542 See android.sensor.frameDuration for more information about 8543 calculating the max frame rate (absent stalls). 8544 </details> 8545 <hal_details> 8546 If possible, it is recommended that all non-JPEG formats 8547 (such as RAW16) should not have a stall duration. RAW10, RAW12, RAW_OPAQUE 8548 and IMPLEMENTATION_DEFINED must not have stall durations. 8549 </hal_details> 8550 <tag id="V1" /> 8551 </entry> 8552 <entry name="streamConfigurationMap" type="int32" visibility="java_public" 8553 synthetic="true" typedef="streamConfigurationMap" 8554 hwlevel="legacy"> 8555 <description>The available stream configurations that this 8556 camera device supports; also includes the minimum frame durations 8557 and the stall durations for each format/size combination. 8558 </description> 8559 <details> 8560 All camera devices will support sensor maximum resolution (defined by 8561 android.sensor.info.activeArraySize) for the JPEG format. 8562 8563 For a given use case, the actual maximum supported resolution 8564 may be lower than what is listed here, depending on the destination 8565 Surface for the image data. For example, for recording video, 8566 the video encoder chosen may have a maximum size limit (e.g. 1080p) 8567 smaller than what the camera (e.g. maximum resolution is 3264x2448) 8568 can provide. 8569 8570 Please reference the documentation for the image data destination to 8571 check if it limits the maximum size for image data. 8572 8573 For applications targeting SDK version older than 31, the following table 8574 describes the minimum required output stream configurations based on the 8575 hardware level (android.info.supportedHardwareLevel): 8576 8577 Format | Size | Hardware Level | Notes 8578 :-------------------------------------------------:|:--------------------------------------------:|:--------------:|:--------------: 8579 {@link android.graphics.ImageFormat#JPEG} | android.sensor.info.activeArraySize (*1) | Any | 8580 {@link android.graphics.ImageFormat#JPEG} | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 8581 {@link android.graphics.ImageFormat#JPEG} | 1280x720 (720p) | Any | if 720p <= activeArraySize 8582 {@link android.graphics.ImageFormat#JPEG} | 640x480 (480p) | Any | if 480p <= activeArraySize 8583 {@link android.graphics.ImageFormat#JPEG} | 320x240 (240p) | Any | if 240p <= activeArraySize 8584 {@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for JPEG | FULL | 8585 {@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for JPEG, up to the maximum video size | LIMITED | 8586 {@link android.graphics.ImageFormat#PRIVATE} | same as YUV_420_888 | Any | 8587 8588 For applications targeting SDK version 31 or newer, if the mobile device declares to be 8589 media performance class 12 or higher by setting 8590 {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 8591 the primary camera devices (first rear/front camera in the camera ID list) will not 8592 support JPEG sizes smaller than 1080p. If the application configures a JPEG stream 8593 smaller than 1080p, the camera device will round up the JPEG image size to at least 8594 1080p. The requirements for IMPLEMENTATION_DEFINED and YUV_420_888 stay the same. 8595 This new minimum required output stream configurations are illustrated by the table below: 8596 8597 Format | Size | Hardware Level | Notes 8598 :-------------------------------------------------:|:--------------------------------------------:|:--------------:|:--------------: 8599 {@link android.graphics.ImageFormat#JPEG} | android.sensor.info.activeArraySize (*1) | Any | 8600 {@link android.graphics.ImageFormat#JPEG} | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 8601 {@link android.graphics.ImageFormat#YUV_420_888} | android.sensor.info.activeArraySize | FULL | 8602 {@link android.graphics.ImageFormat#YUV_420_888} | 1920x1080 (1080p) | FULL | if 1080p <= activeArraySize 8603 {@link android.graphics.ImageFormat#YUV_420_888} | 1280x720 (720) | FULL | if 720p <= activeArraySize 8604 {@link android.graphics.ImageFormat#YUV_420_888} | 640x480 (480p) | FULL | if 480p <= activeArraySize 8605 {@link android.graphics.ImageFormat#YUV_420_888} | 320x240 (240p) | FULL | if 240p <= activeArraySize 8606 {@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for FULL hardware level, up to the maximum video size | LIMITED | 8607 {@link android.graphics.ImageFormat#PRIVATE} | same as YUV_420_888 | Any | 8608 8609 For applications targeting SDK version 31 or newer, if the mobile device doesn't declare 8610 to be media performance class 12 or better by setting 8611 {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 8612 or if the camera device isn't a primary rear/front camera, the minimum required output 8613 stream configurations are the same as for applications targeting SDK version older than 8614 31. 8615 8616 Refer to android.request.availableCapabilities and 8617 [the table](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations) 8618 for additional mandatory stream configurations on a per-capability basis. 8619 8620 *1: For JPEG format, the sizes may be restricted by below conditions: 8621 8622 * The HAL may choose the aspect ratio of each Jpeg size to be one of well known ones 8623 (e.g. 4:3, 16:9, 3:2 etc.). If the sensor maximum resolution 8624 (defined by android.sensor.info.activeArraySize) has an aspect ratio other than these, 8625 it does not have to be included in the supported JPEG sizes. 8626 * Some hardware JPEG encoders may have pixel boundary alignment requirements, such as 8627 the dimensions being a multiple of 16. 8628 Therefore, the maximum JPEG size may be smaller than sensor maximum resolution. 8629 However, the largest JPEG size will be as close as possible to the sensor maximum 8630 resolution given above constraints. It is required that after aspect ratio adjustments, 8631 additional size reduction due to other issues must be less than 3% in area. For example, 8632 if the sensor maximum resolution is 3280x2464, if the maximum JPEG size has aspect 8633 ratio 4:3, and the JPEG encoder alignment requirement is 16, the maximum JPEG size will be 8634 3264x2448. 8635 8636 Exception on 176x144 (QCIF) resolution: camera devices usually have a fixed capability on 8637 downscaling from larger resolution to smaller ones, and the QCIF resolution can sometimes 8638 not be fully supported due to this limitation on devices with high-resolution image 8639 sensors. Therefore, trying to configure a QCIF resolution stream together with any other 8640 stream larger than 1920x1080 resolution (either width or height) might not be supported, 8641 and capture session creation will fail if it is not. 8642 8643 </details> 8644 <hal_details> 8645 Do not set this property directly 8646 (it is synthetic and will not be available at the HAL layer); 8647 set the android.scaler.availableStreamConfigurations instead. 8648 8649 Not all output formats may be supported in a configuration with 8650 an input stream of a particular format. For more details, see 8651 android.scaler.availableInputOutputFormatsMap. 8652 8653 It is recommended (but not mandatory) to also include half/quarter 8654 of sensor maximum resolution for JPEG formats (regardless of hardware 8655 level). 8656 8657 (The following is a rewording of the above required table): 8658 8659 The HAL must include sensor maximum resolution (defined by 8660 android.sensor.info.activeArraySize). 8661 8662 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 8663 the HAL must include all YUV_420_888 sizes that have JPEG sizes listed 8664 here as output streams. 8665 8666 It must also include each below resolution if it is smaller than or 8667 equal to the sensor maximum resolution (for both YUV_420_888 and JPEG 8668 formats), as output streams: 8669 8670 * 240p (320 x 240) 8671 * 480p (640 x 480) 8672 * 720p (1280 x 720) 8673 * 1080p (1920 x 1080) 8674 8675 Note that for Performance Class 12 or higher primary cameras (first rear/front facing 8676 camera in the camera ID list), camera framework filters out JPEG sizes smaller than 8677 1080p depending on applications' targetSdkLevel. The camera HAL must still support the 8678 smaller JPEG sizes to maintain backward compatibility. 8679 8680 For LIMITED capability devices 8681 (`android.info.supportedHardwareLevel == LIMITED`), 8682 the HAL only has to list up to the maximum video size 8683 supported by the device. 8684 8685 Regardless of hardware level, every output resolution available for 8686 YUV_420_888 must also be available for IMPLEMENTATION_DEFINED. 8687 8688 This supersedes the following fields, which are now deprecated: 8689 8690 * availableFormats 8691 * available[Processed,Raw,Jpeg]Sizes 8692 </hal_details> 8693 </entry> 8694 <entry name="croppingType" type="byte" visibility="public" enum="true" 8695 hwlevel="legacy"> 8696 <enum> 8697 <value>CENTER_ONLY 8698 <notes> 8699 The camera device only supports centered crop regions. 8700 </notes> 8701 </value> 8702 <value>FREEFORM 8703 <notes> 8704 The camera device supports arbitrarily chosen crop regions. 8705 </notes> 8706 </value> 8707 </enum> 8708 <description>The crop type that this camera device supports.</description> 8709 <details> 8710 When passing a non-centered crop region (android.scaler.cropRegion) to a camera 8711 device that only supports CENTER_ONLY cropping, the camera device will move the 8712 crop region to the center of the sensor active array (android.sensor.info.activeArraySize) 8713 and keep the crop region width and height unchanged. The camera device will return the 8714 final used crop region in metadata result android.scaler.cropRegion. 8715 8716 Camera devices that support FREEFORM cropping will support any crop region that 8717 is inside of the active array. The camera device will apply the same crop region and 8718 return the final used crop region in capture result metadata android.scaler.cropRegion. 8719 8720 Starting from API level 30, 8721 8722 * If the camera device supports FREEFORM cropping, in order to do FREEFORM cropping, the 8723 application must set android.control.zoomRatio to 1.0, and use android.scaler.cropRegion 8724 for zoom. 8725 * To do CENTER_ONLY zoom, the application has below 2 options: 8726 1. Set android.control.zoomRatio to 1.0; adjust zoom by android.scaler.cropRegion. 8727 2. Adjust zoom by android.control.zoomRatio; use android.scaler.cropRegion to crop 8728 the field of view vertically (letterboxing) or horizontally (pillarboxing), but not 8729 windowboxing. 8730 * Setting android.control.zoomRatio to values different than 1.0 and 8731 android.scaler.cropRegion to be windowboxing at the same time are not supported. In this 8732 case, the camera framework will override the android.scaler.cropRegion to be the active 8733 array. 8734 8735 LEGACY capability devices will only support CENTER_ONLY cropping. 8736 </details> 8737 <hal_details> 8738 If the HAL supports android.control.zoomRatio, this tag must be set to CENTER_ONLY. 8739 </hal_details> 8740 </entry> 8741 <entry name="availableRecommendedStreamConfigurations" type="int32" visibility="ndk_public" 8742 optional="true" enum="true" container="array" typedef="recommendedStreamConfiguration" 8743 hal_version="3.4"> 8744 <array> 8745 <size>n</size> 8746 <size>5</size> 8747 </array> 8748 <enum> 8749 <value id="0x0">PREVIEW 8750 <notes> 8751 Preview must only include non-stalling processed stream configurations with 8752 output formats like 8753 {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888}, 8754 {@link android.graphics.ImageFormat#PRIVATE|AIMAGE_FORMAT_PRIVATE}, etc. 8755 </notes> 8756 </value> 8757 <value id="0x1">RECORD 8758 <notes> 8759 Video record must include stream configurations that match the advertised 8760 supported media profiles {@link android.media.CamcorderProfile} with 8761 IMPLEMENTATION_DEFINED format. 8762 </notes> 8763 </value> 8764 <value id="0x2">VIDEO_SNAPSHOT 8765 <notes> 8766 Video snapshot must include stream configurations at least as big as 8767 the maximum RECORD resolutions and only with 8768 {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG output format}. 8769 Additionally the configurations shouldn't cause preview glitches and also be able to 8770 run at 30 fps. 8771 </notes> 8772 </value> 8773 <value id="0x3">SNAPSHOT 8774 <notes> 8775 Recommended snapshot stream configurations must include at least one with 8776 size close to android.sensor.info.activeArraySize and 8777 {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG output format}. 8778 Taking into account restrictions on aspect ratio, alignment etc. the area of the 8779 maximum suggested size shouldn’t be less than 97% of the sensor array size area. 8780 </notes> 8781 </value> 8782 <value id="0x4">ZSL 8783 <notes> 8784 If supported, recommended input stream configurations must only be advertised with 8785 ZSL along with other processed and/or stalling output formats. 8786 </notes> 8787 </value> 8788 <value id="0x5">RAW 8789 <notes> 8790 If supported, recommended raw stream configurations must only include RAW based 8791 output formats. 8792 </notes> 8793 </value> 8794 <value id="0x6">LOW_LATENCY_SNAPSHOT 8795 <notes> 8796 If supported, the recommended low latency stream configurations must have 8797 end-to-end latency that does not exceed 200 ms. under standard operating conditions 8798 (reasonable light levels, not loaded system) and using template 8799 TEMPLATE_STILL_CAPTURE. This is primarily for listing configurations for the 8800 {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG output format} 8801 however other supported output formats can be added as well. 8802 </notes> 8803 </value> 8804 <value id="0x7">PUBLIC_END 8805 </value> 8806 <value id="0x8" hal_version="3.8">10BIT_OUTPUT 8807 <notes> 8808 If supported, the recommended 10-bit output stream configurations must include 8809 a subset of the advertised {@link android.graphics.ImageFormat#YCBCR_P010} and 8810 {@link android.graphics.ImageFormat#PRIVATE} outputs that are optimized for power 8811 and performance when registered along with a supported 10-bit dynamic range profile. 8812 see android.hardware.camera2.params.OutputConfiguration#setDynamicRangeProfile for 8813 details. 8814 </notes> 8815 </value> 8816 <value id="0x9" hal_version="3.8">PUBLIC_END_3_8 8817 </value> 8818 <value id="0x18">VENDOR_START 8819 <notes> 8820 Vendor defined use cases. These depend on the vendor implementation. 8821 </notes> 8822 </value> 8823 </enum> 8824 <description>Recommended stream configurations for common client use cases. 8825 </description> 8826 <details>Optional subset of the android.scaler.availableStreamConfigurations that contains 8827 similar tuples listed as 8828 (i.e. width, height, format, output/input stream, usecase bit field). 8829 Camera devices will be able to suggest particular stream configurations which are 8830 power and performance efficient for specific use cases. For more information about 8831 retrieving the suggestions see 8832 {@link android.hardware.camera2.CameraCharacteristics#getRecommendedStreamConfigurationMap}. 8833 </details> 8834 <ndk_details> 8835 The data representation is int[5], which maps to 8836 (width, height, format, output/input stream, usecase bit field). The array can be 8837 parsed using the following pseudo code: 8838 8839 struct StreamConfiguration { 8840 int32_t format; 8841 int32_t width; 8842 int32_t height; 8843 int32_t isInput; }; 8844 8845 void getPreferredStreamConfigurations( 8846 int32_t *array, size_t count, int32_t usecaseId, 8847 Vector < StreamConfiguration > * scs) { 8848 const size_t STREAM_CONFIGURATION_SIZE = 5; 8849 const size_t STREAM_WIDTH_OFFSET = 0; 8850 const size_t STREAM_HEIGHT_OFFSET = 1; 8851 const size_t STREAM_FORMAT_OFFSET = 2; 8852 const size_t STREAM_IS_INPUT_OFFSET = 3; 8853 const size_t STREAM_USECASE_BITMAP_OFFSET = 4; 8854 8855 for (size_t i = 0; i < count; i+= STREAM_CONFIGURATION_SIZE) { 8856 int32_t width = array[i + STREAM_WIDTH_OFFSET]; 8857 int32_t height = array[i + STREAM_HEIGHT_OFFSET]; 8858 int32_t format = array[i + STREAM_FORMAT_OFFSET]; 8859 int32_t isInput = array[i + STREAM_IS_INPUT_OFFSET]; 8860 int32_t supportedUsecases = array[i + STREAM_USECASE_BITMAP_OFFSET]; 8861 if (supportedUsecases & (1 << usecaseId)) { 8862 StreamConfiguration sc = {format, width, height, isInput}; 8863 scs->add(sc); 8864 } 8865 } 8866 } 8867 8868 </ndk_details> 8869 <hal_details> 8870 There are some requirements that need to be considered regarding the usecases and the 8871 suggested configurations: 8872 8873 * If android.scaler.availableRecommendedStreamConfigurations is set, then recommended 8874 stream configurations must be present for all mandatory usecases PREVIEW, 8875 SNAPSHOT, RECORD, VIDEO_SNAPSHOT. ZSL and RAW are 8876 required depending on device capabilities see android.request.availableCapabilities. 8877 * Non-existing usecases and non-vendor usecases within the range 8878 (RAW : VENDOR_START] are prohibited as well as stream configurations not 8879 present in the exhaustive android.scaler.availableStreamConfigurations list. 8880 8881 For example, in case the camera device supports only 4K and 1080p and both resolutions are 8882 recommended for the mandatory usecases except preview which can run efficiently only 8883 on 1080p. The array may look like this: 8884 8885 [3840, 2160, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 8886 ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT, 8887 (1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD | 8888 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT | 8889 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT), 8890 8891 1920, 1080, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 8892 ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT, 8893 (1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_PREVIEW | 8894 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD | 8895 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT | 8896 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT)] 8897 8898 </hal_details> 8899 </entry> 8900 <entry name="availableRecommendedInputOutputFormatsMap" type="int32" visibility="ndk_public" 8901 optional="true" typedef="reprocessFormatsMap" hal_version="3.4"> 8902 <description>Recommended mappings of image formats that are supported by this 8903 camera device for input streams, to their corresponding output formats. 8904 </description> 8905 <details> 8906 This is a recommended subset of the complete list of mappings found in 8907 android.scaler.availableInputOutputFormatsMap. The same requirements apply here as well. 8908 The list however doesn't need to contain all available and supported mappings. Instead of 8909 this developers must list only recommended and efficient entries. 8910 If set, the information will be available in the ZERO_SHUTTER_LAG recommended stream 8911 configuration see 8912 {@link android.hardware.camera2.CameraCharacteristics#getRecommendedStreamConfigurationMap}. 8913 </details> 8914 <hal_details> 8915 For a code sample of the required data encoding please check 8916 android.scaler.availableInputOutputFormatsMap. 8917 </hal_details> 8918 <tag id="REPROC" /> 8919 </entry> 8920 <entry name="mandatoryStreamCombinations" type="int32" visibility="java_public" 8921 synthetic="true" container="array" typedef="mandatoryStreamCombination" hwlevel="limited"> 8922 <array> 8923 <size>n</size> 8924 </array> 8925 <description> 8926 An array of mandatory stream combinations generated according to the camera device 8927 {@link android.hardware.camera2.CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 8928 and {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES}. 8929 This is an app-readable conversion of the mandatory stream combination 8930 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations). 8931 </description> 8932 <details> 8933 The array of 8934 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 8935 generated according to the documented 8936 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations). 8937 based on specific device level and capabilities. 8938 Clients can use the array as a quick reference to find an appropriate camera stream 8939 combination. 8940 As per documentation, the stream combinations with given PREVIEW, RECORD and 8941 MAXIMUM resolutions and anything smaller from the list given by 8942 {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} are 8943 guaranteed to work. 8944 For a physical camera not independently exposed in 8945 {@link android.hardware.camera2.CameraManager#getCameraIdList}, the mandatory stream 8946 combinations for that physical camera Id are also generated, so that the application can 8947 configure them as physical streams via the logical camera. 8948 The mandatory stream combination array will be {@code null} in case the device is not 8949 backward compatible. 8950 </details> 8951 <hal_details> 8952 Do not set this property directly 8953 (it is synthetic and will not be available at the HAL layer). 8954 </hal_details> 8955 </entry> 8956 <entry name="mandatoryConcurrentStreamCombinations" type="int32" visibility="java_public" 8957 synthetic="true" container="array" typedef="mandatoryStreamCombination"> 8958 <array> 8959 <size>n</size> 8960 </array> 8961 <description> 8962 An array of mandatory concurrent stream combinations. 8963 This is an app-readable conversion of the concurrent mandatory stream combination 8964 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#concurrent-stream-guaranteed-configurations). 8965 </description> 8966 <details> 8967 The array of 8968 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 8969 generated according to the documented 8970 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#concurrent-stream-guaranteed-configurations) 8971 for each device which has its Id present in the set returned by 8972 {@link android.hardware.camera2.CameraManager#getConcurrentCameraIds}. 8973 Clients can use the array as a quick reference to find an appropriate camera stream 8974 combination. 8975 The mandatory stream combination array will be {@code null} in case the device is not a 8976 part of at least one set of combinations returned by 8977 {@link android.hardware.camera2.CameraManager#getConcurrentCameraIds}. 8978 </details> 8979 <hal_details> 8980 Do not set this property directly 8981 (it is synthetic and will not be available at the HAL layer). 8982 </hal_details> 8983 </entry> 8984 <entry name="availableRotateAndCropModes" type="byte" visibility="public" 8985 type_notes="list of enums" container="array" typedef="enumList" 8986 hal_version="3.5"> 8987 <array> 8988 <size>n</size> 8989 </array> 8990 <description> 8991 List of rotate-and-crop modes for android.scaler.rotateAndCrop that are supported by this camera device. 8992 </description> 8993 <range>Any value listed in android.scaler.rotateAndCrop</range> 8994 <details> 8995 This entry lists the valid modes for android.scaler.rotateAndCrop for this camera device. 8996 8997 Starting with API level 30, all devices will list at least `ROTATE_AND_CROP_NONE`. 8998 Devices with support for rotate-and-crop will additionally list at least 8999 `ROTATE_AND_CROP_AUTO` and `ROTATE_AND_CROP_90`. 9000 </details> 9001 </entry> 9002 </static> 9003 <controls> 9004 <entry name="rotateAndCrop" type="byte" visibility="public" enum="true" 9005 hal_version="3.5"> 9006 <enum> 9007 <value>NONE 9008 <notes>No rotate and crop is applied. Processed outputs are in the sensor orientation. 9009 </notes> 9010 </value> 9011 <value>90 9012 <notes>Processed images are rotated by 90 degrees clockwise, and then cropped 9013 to the original aspect ratio.</notes> 9014 </value> 9015 <value>180 9016 <notes>Processed images are rotated by 180 degrees. Since the aspect ratio does not 9017 change, no cropping is performed.</notes> 9018 </value> 9019 <value>270 9020 <notes>Processed images are rotated by 270 degrees clockwise, and then cropped 9021 to the original aspect ratio.</notes> 9022 </value> 9023 <value>AUTO 9024 <notes>The camera API automatically selects the best concrete value for 9025 rotate-and-crop based on the application's support for resizability and the current 9026 multi-window mode. 9027 9028 If the application does not support resizing but the display mode for its main 9029 Activity is not in a typical orientation, the camera API will set `ROTATE_AND_CROP_90` 9030 or some other supported rotation value, depending on device configuration, 9031 to ensure preview and captured images are correctly shown to the user. Otherwise, 9032 `ROTATE_AND_CROP_NONE` will be selected. 9033 9034 When a value other than NONE is selected, several metadata fields will also be parsed 9035 differently to ensure that coordinates are correctly handled for features like drawing 9036 face detection boxes or passing in tap-to-focus coordinates. The camera API will 9037 convert positions in the active array coordinate system to/from the cropped-and-rotated 9038 coordinate system to make the operation transparent for applications. 9039 9040 No coordinate mapping will be done when the application selects a non-AUTO mode. 9041 </notes> 9042 </value> 9043 </enum> 9044 <description>Whether a rotation-and-crop operation is applied to processed 9045 outputs from the camera.</description> 9046 <range>android.scaler.availableRotateAndCropModes</range> 9047 <details> 9048 This control is primarily intended to help camera applications with no support for 9049 multi-window modes to work correctly on devices where multi-window scenarios are 9050 unavoidable, such as foldables or other devices with variable display geometry or more 9051 free-form window placement (such as laptops, which often place portrait-orientation apps 9052 in landscape with pillarboxing). 9053 9054 If supported, the default value is `ROTATE_AND_CROP_AUTO`, which allows the camera API 9055 to enable backwards-compatibility support for applications that do not support resizing 9056 / multi-window modes, when the device is in fact in a multi-window mode (such as inset 9057 portrait on laptops, or on a foldable device in some fold states). In addition, 9058 `ROTATE_AND_CROP_NONE` and `ROTATE_AND_CROP_90` will always be available if this control 9059 is supported by the device. If not supported, devices API level 30 or higher will always 9060 list only `ROTATE_AND_CROP_NONE`. 9061 9062 When `CROP_AUTO` is in use, and the camera API activates backward-compatibility mode, 9063 several metadata fields will also be parsed differently to ensure that coordinates are 9064 correctly handled for features like drawing face detection boxes or passing in 9065 tap-to-focus coordinates. The camera API will convert positions in the active array 9066 coordinate system to/from the cropped-and-rotated coordinate system to make the 9067 operation transparent for applications. The following controls are affected: 9068 9069 * android.control.aeRegions 9070 * android.control.afRegions 9071 * android.control.awbRegions 9072 * android.statistics.faces 9073 9074 Capture results will contain the actual value selected by the API; 9075 `ROTATE_AND_CROP_AUTO` will never be seen in a capture result. 9076 9077 Applications can also select their preferred cropping mode, either to opt out of the 9078 backwards-compatibility treatment, or to use the cropping feature themselves as needed. 9079 In this case, no coordinate translation will be done automatically, and all controls 9080 will continue to use the normal active array coordinates. 9081 9082 Cropping and rotating is done after the application of digital zoom (via either 9083 android.scaler.cropRegion or android.control.zoomRatio), but before each individual 9084 output is further cropped and scaled. It only affects processed outputs such as 9085 YUV, PRIVATE, and JPEG. It has no effect on RAW outputs. 9086 9087 When `CROP_90` or `CROP_270` are selected, there is a significant loss to the field of 9088 view. For example, with a 4:3 aspect ratio output of 1600x1200, `CROP_90` will still 9089 produce 1600x1200 output, but these buffers are cropped from a vertical 3:4 slice at the 9090 center of the 4:3 area, then rotated to be 4:3, and then upscaled to 1600x1200. Only 9091 56.25% of the original FOV is still visible. In general, for an aspect ratio of `w:h`, 9092 the crop and rotate operation leaves `(h/w)^2` of the field of view visible. For 16:9, 9093 this is ~31.6%. 9094 9095 As a visual example, the figure below shows the effect of `ROTATE_AND_CROP_90` on the 9096 outputs for the following parameters: 9097 9098 * Sensor active array: `2000x1500` 9099 * Crop region: top-left: `(500, 375)`, size: `(1000, 750)` (4:3 aspect ratio) 9100 * Output streams: YUV `640x480` and YUV `1280x720` 9101 * `ROTATE_AND_CROP_90` 9102 9103  9104 9105 With these settings, the regions of the active array covered by the output streams are: 9106 9107 * 640x480 stream crop: top-left: `(219, 375)`, size: `(562, 750)` 9108 * 1280x720 stream crop: top-left: `(289, 375)`, size: `(422, 750)` 9109 9110 Since the buffers are rotated, the buffers as seen by the application are: 9111 9112 * 640x480 stream: top-left: `(781, 375)` on active array, size: `(640, 480)`, downscaled 1.17x from sensor pixels 9113 * 1280x720 stream: top-left: `(711, 375)` on active array, size: `(1280, 720)`, upscaled 1.71x from sensor pixels 9114 </details> 9115 <hal_details> 9116 ROTATE_AND_CROP_AUTO will never be sent to the HAL, though it must be set as the default 9117 value in all the capture request templates by the HAL. The camera service will 9118 translate AUTO to a specific rotation value based on the current application's 9119 multi-window state and its support of resizability. 9120 9121 The HAL also does not need to consider coordinate transforms for ROTATE_AND_CROP - all 9122 capture request and result fields should be kept in the active array coordinate frame. 9123 Any translation required to implement ROTATE_AND_CROP_AUTO will be handled by the camera 9124 service. 9125 </hal_details> 9126 </entry> 9127 </controls> 9128 <dynamic> 9129 <clone entry="android.scaler.rotateAndCrop" kind="controls" hal_version="3.5"> 9130 </clone> 9131 </dynamic> 9132 <static> 9133 <entry name="defaultSecureImageSize" type="int32" visibility="public" 9134 type_notes="width/height for the default secure image data size" container="array" 9135 typedef="size" hal_version="3.6"> 9136 <array> 9137 <size>2</size> 9138 </array> 9139 <description> 9140 Default YUV/PRIVATE size to use for requesting secure image buffers. 9141 </description> 9142 <units>Pixels</units> 9143 <details> 9144 This entry lists the default size supported in the secure camera mode. This entry is 9145 optional on devices support the SECURE_IMAGE_DATA capability. This entry will be null 9146 if the camera device does not list SECURE_IMAGE_DATA capability. 9147 9148 When the key is present, only a PRIVATE/YUV output of the specified size is guaranteed 9149 to be supported by the camera HAL in the secure camera mode. Any other format or 9150 resolutions might not be supported. Use 9151 {@link CameraDevice#isSessionConfigurationSupported|ACameraDevice_isSessionConfigurationSupported} 9152 API to query if a secure session configuration is supported if the device supports this 9153 API. 9154 9155 If this key returns null on a device with SECURE_IMAGE_DATA capability, the application 9156 can assume all output sizes listed in the 9157 {@link 9158 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS} 9159 are supported. 9160 </details> 9161 </entry> 9162 <entry name="physicalCameraMultiResolutionStreamConfigurations" type="int32" 9163 visibility="ndk_public" optional="true" enum="true" container="array" 9164 typedef="streamConfiguration" hwlevel="limited" hal_version="3.6"> 9165 <array> 9166 <size>n</size> 9167 <size>4</size> 9168 </array> 9169 <enum> 9170 <value>OUTPUT</value> 9171 <value>INPUT</value> 9172 </enum> 9173 <description>The available multi-resolution stream configurations that this 9174 physical camera device supports 9175 (i.e. format, width, height, output/input stream). 9176 </description> 9177 <details> 9178 This list contains a subset of the parent logical camera's multi-resolution stream 9179 configurations which belong to this physical camera, and it will advertise and will only 9180 advertise the maximum supported resolutions for a particular format. 9181 9182 If this camera device isn't a physical camera device constituting a logical camera, 9183 but a standalone {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 9184 camera, this field represents the multi-resolution input/output stream configurations of 9185 default mode and max resolution modes. The sizes will be the maximum resolution of a 9186 particular format for default mode and max resolution mode. 9187 9188 This field will only be advertised if the device is a physical camera of a 9189 logical multi-camera device or an ultra high resolution sensor camera. For a logical 9190 multi-camera, the camera API will derive the logical camera’s multi-resolution stream 9191 configurations from all physical cameras. For an ultra high resolution sensor camera, this 9192 is used directly as the camera’s multi-resolution stream configurations. 9193 </details> 9194 <hal_details> 9195 If this field contains input stream configurations, and the camera device is a physical 9196 camera (not a standalone ultra-high resolution camera), the 9197 android.logicalMultiCamera.activePhysicalId tag must be set to the physical camera Id in 9198 the physical camera result metadata. This is to make sure during multi-resolution 9199 reprocessing, the camera HAL is notified of which physical camera the reprocessing 9200 request comes from. 9201 </hal_details> 9202 </entry> 9203 <entry name="multiResolutionStreamConfigurationMap" type="int32" visibility="java_public" 9204 synthetic="true" optional="true" typedef="multiResolutionStreamConfigurationMap"> 9205 <description>The multi-resolution stream configurations supported by this logical camera 9206 or ultra high resolution sensor camera device. 9207 </description> 9208 <details> 9209 Multi-resolution streams can be used by a LOGICAL_MULTI_CAMERA or an 9210 ULTRA_HIGH_RESOLUTION_SENSOR camera where the images sent or received can vary in 9211 resolution per frame. This is useful in cases where the camera device's effective full 9212 resolution changes depending on factors such as the current zoom level, lighting 9213 condition, focus distance, or pixel mode. 9214 9215 * For a logical multi-camera implementing optical zoom, at different zoom level, a 9216 different physical camera may be active, resulting in different full-resolution image 9217 sizes. 9218 * For an ultra high resolution camera, depending on whether the camera operates in default 9219 mode, or maximum resolution mode, the output full-size images may be of either binned 9220 resolution or maximum resolution. 9221 9222 To use multi-resolution output streams, the supported formats can be queried by {@link 9223 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputFormats}. 9224 A {@link android.hardware.camera2.MultiResolutionImageReader} can then be created for a 9225 supported format with the MultiResolutionStreamInfo group queried by {@link 9226 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputInfo}. 9227 9228 If a camera device supports multi-resolution output streams for a particular format, for 9229 each of its mandatory stream combinations, the camera device will support using a 9230 MultiResolutionImageReader for the MAXIMUM stream of supported formats. Refer to 9231 [the table](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-additional-guaranteed-combinations-with-multiresolutionoutputs) 9232 for additional details. 9233 9234 To use multi-resolution input streams, the supported formats can be queried by {@link 9235 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getInputFormats}. 9236 A reprocessable CameraCaptureSession can then be created using an {@link 9237 android.hardware.camera2.params.InputConfiguration InputConfiguration} constructed with 9238 the input MultiResolutionStreamInfo group, queried by {@link 9239 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getInputInfo}. 9240 9241 If a camera device supports multi-resolution {@code YUV} input and multi-resolution 9242 {@code YUV} output, or multi-resolution {@code PRIVATE} input and multi-resolution 9243 {@code PRIVATE} output, {@code JPEG} and {@code YUV} are guaranteed to be supported 9244 multi-resolution output stream formats. Refer to 9245 [the table](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-additional-guaranteed-combinations-with-multiresolutionoutputs) 9246 for details about the additional mandatory stream combinations in this case. 9247 </details> 9248 <hal_details> 9249 Do not set this property directly 9250 (it is synthetic and will not be available at the HAL layer). 9251 </hal_details> 9252 </entry> 9253 <entry name="availableStreamConfigurationsMaximumResolution" type="int32" 9254 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 9255 hal_version="3.6"> 9256 <array> 9257 <size>n</size> 9258 <size>4</size> 9259 </array> 9260 <enum> 9261 <value>OUTPUT</value> 9262 <value>INPUT</value> 9263 </enum> 9264 <description>The available stream configurations that this 9265 camera device supports (i.e. format, width, height, output/input stream) for a 9266 CaptureRequest with android.sensor.pixelMode set to 9267 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9268 </description> 9269 <details> 9270 Analogous to android.scaler.availableStreamConfigurations, for configurations 9271 which are applicable when android.sensor.pixelMode is set to 9272 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9273 9274 Not all output formats may be supported in a configuration with 9275 an input stream of a particular format. For more details, see 9276 android.scaler.availableInputOutputFormatsMapMaximumResolution. 9277 </details> 9278 <hal_details> 9279 Refer to hal_details for android.scaler.availableStreamConfigurations. 9280 </hal_details> 9281 </entry> 9282 <entry name="availableMinFrameDurationsMaximumResolution" type="int64" visibility="ndk_public" 9283 container="array" typedef="streamConfigurationDuration" hal_version="3.6"> 9284 <array> 9285 <size>4</size> 9286 <size>n</size> 9287 </array> 9288 <description>This lists the minimum frame duration for each 9289 format/size combination when the camera device is sent a CaptureRequest with 9290 android.sensor.pixelMode set to 9291 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9292 </description> 9293 <units>(format, width, height, ns) x n</units> 9294 <details> 9295 Analogous to android.scaler.availableMinFrameDurations, for configurations 9296 which are applicable when android.sensor.pixelMode is set to 9297 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9298 9299 When multiple streams are used in a request (if supported, when android.sensor.pixelMode 9300 is set to 9301 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}), the 9302 minimum frame duration will be max(individual stream min durations). 9303 9304 See android.sensor.frameDuration and 9305 android.scaler.availableStallDurationsMaximumResolution for more details about 9306 calculating the max frame rate. 9307 </details> 9308 </entry> 9309 <entry name="availableStallDurationsMaximumResolution" type="int64" visibility="ndk_public" 9310 container="array" typedef="streamConfigurationDuration" hal_version="3.6"> 9311 <array> 9312 <size>4</size> 9313 <size>n</size> 9314 </array> 9315 <description>This lists the maximum stall duration for each 9316 output format/size combination when CaptureRequests are submitted with 9317 android.sensor.pixelMode set to 9318 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 9319 </description> 9320 <units>(format, width, height, ns) x n</units> 9321 <details> 9322 Analogous to android.scaler.availableMinFrameDurations, for configurations 9323 which are applicable when android.sensor.pixelMode is set to 9324 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9325 </details> 9326 <hal_details> 9327 If possible, it is recommended that all non-JPEG formats 9328 (such as RAW16) should not have a stall duration. RAW10, RAW12, RAW_OPAQUE 9329 and IMPLEMENTATION_DEFINED must not have stall durations. 9330 </hal_details> 9331 </entry> 9332 <entry name="streamConfigurationMapMaximumResolution" type="int32" visibility="java_public" 9333 synthetic="true" typedef="streamConfigurationMap"> 9334 <description>The available stream configurations that this 9335 camera device supports when given a CaptureRequest with android.sensor.pixelMode 9336 set to 9337 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}; 9338 also includes the minimum frame durations 9339 and the stall durations for each format/size combination. 9340 </description> 9341 <details> 9342 Analogous to android.scaler.streamConfigurationMap for CaptureRequests where 9343 android.sensor.pixelMode is 9344 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9345 </details> 9346 <hal_details> 9347 Do not set this property directly 9348 (it is synthetic and will not be available at the HAL layer); 9349 set the android.scaler.availableStreamConfigurationsMaximumResolution instead. 9350 9351 Not all output formats may be supported in a configuration with 9352 an input stream of a particular format. For more details, see 9353 android.scaler.availableInputOutputFormatsMapMaximumResolution. 9354 </hal_details> 9355 </entry> 9356 <entry name="availableInputOutputFormatsMapMaximumResolution" type="int32" 9357 visibility="hidden" typedef="reprocessFormatsMap" hal_version="3.6"> 9358 <description>The mapping of image formats that are supported by this 9359 camera device for input streams, to their corresponding output formats, when 9360 android.sensor.pixelMode is set to 9361 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9362 </description> 9363 <details> 9364 Analogous to android.scaler.availableInputOutputFormatsMap for CaptureRequests where 9365 android.sensor.pixelMode is 9366 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9367 </details> 9368 <hal_details> 9369 Refer to hal details for android.scaler.availableInputOutputFormatsMapMaximumResolution. 9370 </hal_details> 9371 <tag id="REPROC" /> 9372 </entry> 9373 <entry name="mandatoryMaximumResolutionStreamCombinations" type="int32" 9374 visibility="java_public" synthetic="true" container="array" 9375 typedef="mandatoryStreamCombination"> 9376 <array> 9377 <size>n</size> 9378 </array> 9379 <description> 9380 An array of mandatory stream combinations which are applicable when 9381 {@link android.hardware.camera2.CaptureRequest} has android.sensor.pixelMode set 9382 to {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9383 This is an app-readable conversion of the maximum resolution mandatory stream combination 9384 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#additional-guaranteed-combinations-for-ultra-high-resolution-sensors). 9385 </description> 9386 <details> 9387 The array of 9388 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 9389 generated according to the documented 9390 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#additional-guaranteed-combinations-for-ultra-high-resolution-sensors) 9391 for each device which has the 9392 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 9393 capability. 9394 Clients can use the array as a quick reference to find an appropriate camera stream 9395 combination. 9396 The mandatory stream combination array will be {@code null} in case the device is not an 9397 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 9398 device. 9399 </details> 9400 <hal_details> 9401 Do not set this property directly 9402 (it is synthetic and will not be available at the HAL layer). 9403 </hal_details> 9404 </entry> 9405 <entry name="mandatoryTenBitOutputStreamCombinations" type="int32" 9406 visibility="java_public" synthetic="true" container="array" 9407 typedef="mandatoryStreamCombination"> 9408 <array> 9409 <size>n</size> 9410 </array> 9411 <description> 9412 An array of mandatory stream combinations which are applicable when device support the 9413 10-bit output capability 9414 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 9415 This is an app-readable conversion of the 10 bit output mandatory stream combination 9416 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#10-bit-output-additional-guaranteed-configurations). 9417 </description> 9418 <details> 9419 The array of 9420 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 9421 generated according to the documented 9422 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#10-bit-output-additional-guaranteed-configurations) 9423 for each device which has the 9424 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 9425 capability. 9426 Clients can use the array as a quick reference to find an appropriate camera stream 9427 combination. 9428 The mandatory stream combination array will be {@code null} in case the device is not an 9429 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 9430 device. 9431 </details> 9432 <hal_details> 9433 Do not set this property directly 9434 (it is synthetic and will not be available at the HAL layer). 9435 </hal_details> 9436 </entry> 9437 <entry name="mandatoryPreviewStabilizationOutputStreamCombinations" type="int32" 9438 visibility="java_public" synthetic="true" container="array" 9439 typedef="mandatoryStreamCombination"> 9440 <array> 9441 <size>n</size> 9442 </array> 9443 <description> 9444 An array of mandatory stream combinations which are applicable when device lists 9445 {@code PREVIEW_STABILIZATION} in android.control.availableVideoStabilizationModes. 9446 This is an app-readable conversion of the preview stabilization mandatory stream 9447 combination 9448 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#preview-stabilization-guaranteed-stream-configurations). 9449 </description> 9450 <details> 9451 The array of 9452 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 9453 generated according to the documented 9454 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#preview-stabilization-guaranteed-stream-configurations) 9455 for each device which supports {@code PREVIEW_STABILIZATION} 9456 Clients can use the array as a quick reference to find an appropriate camera stream 9457 combination. 9458 The mandatory stream combination array will be {@code null} in case the device does not 9459 list {@code PREVIEW_STABILIZATION} in android.control.availableVideoStabilizationModes. 9460 </details> 9461 <hal_details> 9462 Do not set this property directly 9463 (it is synthetic and will not be available at the HAL layer). 9464 </hal_details> 9465 </entry> 9466 9467 <entry name="multiResolutionStreamSupported" type="byte" visibility="ndk_public" enum="true" 9468 typedef="boolean" hwlevel="limited" hal_version="3.6"> 9469 <enum> 9470 <value>FALSE</value> 9471 <value>TRUE</value> 9472 </enum> 9473 <description>Whether the camera device supports multi-resolution input or output streams 9474 </description> 9475 <details> 9476 A logical multi-camera or an ultra high resolution camera may support multi-resolution 9477 input or output streams. With multi-resolution output streams, the camera device is able 9478 to output different resolution images depending on the current active physical camera or 9479 pixel mode. With multi-resolution input streams, the camera device can reprocess images 9480 of different resolutions from different physical cameras or sensor pixel modes. 9481 9482 When set to TRUE: 9483 9484 * For a logical multi-camera, the camera framework derives 9485 android.scaler.multiResolutionStreamConfigurationMap by combining the 9486 android.scaler.physicalCameraMultiResolutionStreamConfigurations from its physical 9487 cameras. 9488 * For an ultra-high resolution sensor camera, the camera framework directly copies 9489 the value of android.scaler.physicalCameraMultiResolutionStreamConfigurations to 9490 android.scaler.multiResolutionStreamConfigurationMap. 9491 </details> 9492 <hal_details> 9493 For the HAL to claim support for multi-resolution streams: 9494 9495 * The HAL must support the buffer management API by setting 9496 supportedBufferManagementVersion to HIDL_DEVICE_3_5. 9497 * For a logical multi-camera, when combined from all its physical cameras, there must be 9498 at a minimum one input or output stream format with at least two different 9499 physicalCameraMultiResolutionStreamConfigurations entries for that format. 9500 * For an ultra high resolution sensor camera, for each supported multi-resolution format, 9501 the physicalCameraMultiResolutionStreamConfigurations must contain both the largest stream 9502 configuration within the android.scaler.streamConfigurationMap and the largest stream 9503 configuration within the android.scaler.streamConfigurationMapMaximumResolution. 9504 * If the HAL advertises multi-resolution input stream support for a particular format 9505 (namely PRIVATE, or YUV), the logical multi-camera or ultra high resolution sensor camera 9506 must have the corresponding reprocessing capabilities (PRIVATE_REPROCESSING, 9507 or YUV_REPROCESSING respectively). The camera HAL must support reprocessing the 9508 multi-resolution input stream to the output formats specified in the camera's 9509 android.scaler.availableInputOutputFormatsMap. 9510 </hal_details> 9511 </entry> 9512 </static> 9513 <controls> 9514 <entry name="cropRegionSet" type="byte" visibility="fwk_only" 9515 enum="true" typedef="boolean"> 9516 <enum> 9517 <value>FALSE 9518 <notes>Crop region (android.scaler.cropRegion) has not been set by the 9519 camera client. 9520 </notes> 9521 </value> 9522 <value>TRUE 9523 <notes> 9524 Scaler crop regions (android.scaler.cropRegion) has been set by the camera 9525 client. 9526 </notes> 9527 </value> 9528 </enum> 9529 <description> 9530 Framework-only private key which informs camera fwk that the scaler crop region 9531 (android.scaler.cropRegion) has been set by the client and it need 9532 not be corrected when android.sensor.pixelMode is set to MAXIMUM_RESOLUTION. 9533 </description> 9534 <details> 9535 This must be set to TRUE by the camera2 java fwk when the camera client sets 9536 android.scaler.cropRegion. 9537 </details> 9538 </entry> 9539 </controls> 9540 <static> 9541 <entry name="availableStreamUseCases" type="int64" visibility="public" 9542 enum="true" container="array" hal_version="3.8"> 9543 <array> 9544 <size>n</size> 9545 </array> 9546 <enum> 9547 <value optional="true" id="0x0">DEFAULT 9548 <notes> 9549 Default stream use case. 9550 9551 This use case is the same as when the application doesn't set any use case for 9552 the stream. The camera device uses the properties of the output target, such as 9553 format, dataSpace, or surface class type, to optimize the image processing pipeline. 9554 </notes> 9555 </value> 9556 <value optional="true" id="0x1">PREVIEW 9557 <notes> 9558 Live stream shown to the user. 9559 9560 Optimized for performance and usability as a viewfinder, but not necessarily for 9561 image quality. The output is not meant to be persisted as saved images or video. 9562 9563 No stall if android.control.* are set to FAST. There may be stall if 9564 they are set to HIGH_QUALITY. This use case has the same behavior as the 9565 default SurfaceView and SurfaceTexture targets. Additionally, this use case can be 9566 used for in-app image analysis. 9567 </notes> 9568 </value> 9569 <value optional="true" id="0x2">STILL_CAPTURE 9570 <notes> 9571 Still photo capture. 9572 9573 Optimized for high-quality high-resolution capture, and not expected to maintain 9574 preview-like frame rates. 9575 9576 The stream may have stalls regardless of whether android.control.* is HIGH_QUALITY. 9577 This use case has the same behavior as the default JPEG and RAW related formats. 9578 </notes> 9579 </value> 9580 <value optional="true" id="0x3">VIDEO_RECORD 9581 <notes> 9582 Recording video clips. 9583 9584 Optimized for high-quality video capture, including high-quality image stabilization 9585 if supported by the device and enabled by the application. As a result, may produce 9586 output frames with a substantial lag from real time, to allow for highest-quality 9587 stabilization or other processing. As such, such an output is not suitable for drawing 9588 to screen directly, and is expected to be persisted to disk or similar for later 9589 playback or processing. Only streams that set the VIDEO_RECORD use case are guaranteed 9590 to have video stabilization applied when the video stabilization control is set 9591 to ON, as opposed to PREVIEW_STABILIZATION. 9592 9593 This use case has the same behavior as the default MediaRecorder and MediaCodec 9594 targets. 9595 </notes> 9596 </value> 9597 <value optional="true" id="0x4">PREVIEW_VIDEO_STILL 9598 <notes> 9599 One single stream used for combined purposes of preview, video, and still capture. 9600 9601 For such multi-purpose streams, the camera device aims to make the best tradeoff 9602 between the individual use cases. For example, the STILL_CAPTURE use case by itself 9603 may have stalls for achieving best image quality. But if combined with PREVIEW and 9604 VIDEO_RECORD, the camera device needs to trade off the additional image processing 9605 for speed so that preview and video recording aren't slowed down. 9606 9607 Similarly, VIDEO_RECORD may produce frames with a substantial lag, but 9608 PREVIEW_VIDEO_STILL must have minimal output delay. This means that to enable video 9609 stabilization with this use case, the device must support and the app must select the 9610 PREVIEW_STABILIZATION mode for video stabilization. 9611 </notes> 9612 </value> 9613 <value optional="true" id="0x5">VIDEO_CALL 9614 <notes> 9615 Long-running video call optimized for both power efficiency and video quality. 9616 9617 The camera sensor may run in a lower-resolution mode to reduce power consumption 9618 at the cost of some image and digital zoom quality. Unlike VIDEO_RECORD, VIDEO_CALL 9619 outputs are expected to work in dark conditions, so are usually accompanied with 9620 variable frame rate settings to allow sufficient exposure time in low light. 9621 </notes> 9622 </value> 9623 <value optional="true" id="0x6" hal_version="3.9">CROPPED_RAW 9624 <notes> 9625 Cropped RAW stream when the client chooses to crop the field of view. 9626 9627 Certain types of image sensors can run in binned modes in order to improve signal to 9628 noise ratio while capturing frames. However, at certain zoom levels and / or when 9629 other scene conditions are deemed fit, the camera sub-system may choose to un-bin and 9630 remosaic the sensor's output. This results in a RAW frame which is cropped in field 9631 of view and yet has the same number of pixels as full field of view RAW, thereby 9632 improving image detail. 9633 9634 The resultant field of view of the RAW stream will be greater than or equal to 9635 croppable non-RAW streams. The effective crop region for this RAW stream will be 9636 reflected in the CaptureResult key android.scaler.rawCropRegion. 9637 9638 If this stream use case is set on a non-RAW stream, i.e. not one of : 9639 9640 * {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16 RAW_SENSOR} 9641 * {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10 RAW10} 9642 * {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12 RAW12} 9643 9644 session configuration is not guaranteed to succeed. 9645 9646 9647 This stream use case may not be supported on some devices. 9648 </notes> 9649 </value> 9650 <value optional="true" visibility="hidden" id="0x10000">VENDOR_START 9651 <notes> 9652 Vendor defined use cases. These depend on the vendor implementation. 9653 </notes> 9654 </value> 9655 </enum> 9656 <description>The stream use cases supported by this camera device.</description> 9657 <details>The stream use case indicates the purpose of a particular camera stream from 9658 the end-user perspective. Some examples of camera use cases are: preview stream for 9659 live viewfinder shown to the user, still capture for generating high quality photo 9660 capture, video record for encoding the camera output for the purpose of future playback, 9661 and video call for live realtime video conferencing. 9662 9663 With this flag, the camera device can optimize the image processing pipeline 9664 parameters, such as tuning, sensor mode, and ISP settings, independent of 9665 the properties of the immediate camera output surface. For example, if the output 9666 surface is a SurfaceTexture, the stream use case flag can be used to indicate whether 9667 the camera frames eventually go to display, video encoder, 9668 still image capture, or all of them combined. 9669 9670 The application sets the use case of a camera stream by calling 9671 {@link android.hardware.camera2.params.OutputConfiguration#setStreamUseCase}. 9672 9673 A camera device with 9674 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE} 9675 capability must support the following stream use cases: 9676 9677 * DEFAULT 9678 * PREVIEW 9679 * STILL_CAPTURE 9680 * VIDEO_RECORD 9681 * PREVIEW_VIDEO_STILL 9682 * VIDEO_CALL 9683 9684 The guaranteed stream combinations related to stream use case for a camera device with 9685 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE} 9686 capability is documented in the camera device 9687 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#stream-use-case-capability-additional-guaranteed-configurations). 9688 The application is strongly recommended to use one of the guaranteed stream combinations. 9689 If the application creates a session with a stream combination not in the guaranteed 9690 list, or with mixed DEFAULT and non-DEFAULT use cases within the same session, 9691 the camera device may ignore some stream use cases due to hardware constraints 9692 and implementation details. 9693 9694 For stream combinations not covered by the stream use case mandatory lists, such as 9695 reprocessable session, constrained high speed session, or RAW stream combinations, the 9696 application should leave stream use cases within the session as DEFAULT. 9697 </details> 9698 <hal_details> 9699 The camera HAL must support DEFAULT stream use case to handle scenarios where the 9700 application doesn't explicitly set a stream's use case flag, in which case the camera 9701 framework sets it to DEFAULT. 9702 </hal_details> 9703 </entry> 9704 <entry name="mandatoryUseCaseStreamCombinations" type="int32" visibility="java_public" 9705 synthetic="true" container="array" typedef="mandatoryStreamCombination"> 9706 <array> 9707 <size>n</size> 9708 </array> 9709 <description> 9710 An array of mandatory stream combinations with stream use cases. 9711 This is an app-readable conversion of the mandatory stream combination 9712 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#stream-use-case-capability-additional-guaranteed-configurations) 9713 with each stream's use case being set. 9714 </description> 9715 <details> 9716 The array of 9717 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 9718 generated according to the documented 9719 [guildeline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#stream-use-case-capability-additional-guaranteed-configurations) 9720 for a camera device with 9721 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE} 9722 capability. 9723 The mandatory stream combination array will be {@code null} in case the device doesn't 9724 have {@link 9725 android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE} 9726 capability. 9727 </details> 9728 <hal_details> 9729 Do not set this property directly 9730 (it is synthetic and will not be available at the HAL layer). 9731 </hal_details> 9732 </entry> 9733 </static> 9734 <dynamic> 9735 <entry name="rawCropRegion" type="int32" visibility="public" container="array" 9736 typedef="rectangle" hal_version="3.9"> 9737 <array> 9738 <size>4</size> 9739 </array> 9740 <description> 9741 The region of the sensor that corresponds to the RAW read out for this 9742 capture when the stream use case of a RAW stream is set to CROPPED_RAW. 9743 </description> 9744 <units>Pixel coordinates relative to 9745 android.sensor.info.activeArraySize or 9746 android.sensor.info.preCorrectionActiveArraySize depending on distortion correction 9747 capability and mode</units> 9748 <details> 9749 The coordinate system follows that of android.sensor.info.preCorrectionActiveArraySize. 9750 9751 This CaptureResult key will be set when the corresponding CaptureRequest has a RAW target 9752 with stream use case set to 9753 {@link android.hardware.camera2.CameraMetadata#SCALER_AVAILABLE_STREAM_USE_CASES_CROPPED_RAW}, 9754 otherwise it will be {@code null}. 9755 The value of this key specifies the region of the sensor used for the RAW capture and can 9756 be used to calculate the corresponding field of view of RAW streams. 9757 This field of view will always be >= field of view for (processed) non-RAW streams for the 9758 capture. Note: The region specified may not necessarily be centered. 9759 9760 For example: Assume a camera device has a pre correction active array size of 9761 {@code {0, 0, 1500, 2000}}. If the RAW_CROP_REGION is {@code {500, 375, 1500, 1125}}, that 9762 corresponds to a centered crop of 1/4th of the full field of view RAW stream. 9763 9764 The metadata keys which describe properties of RAW frames: 9765 9766 * android.statistics.hotPixelMap 9767 * android.statistics.lensShadingCorrectionMap 9768 * android.lens.distortion 9769 * android.lens.poseTranslation 9770 * android.lens.poseRotation 9771 * android.lens.distortion 9772 * android.lens.intrinsicCalibration 9773 9774 should be interpreted in the effective after raw crop field-of-view coordinate system. 9775 In this coordinate system, 9776 {android.sensor.info.preCorrectionActiveArraySize.left, 9777 android.sensor.info.preCorrectionActiveArraySize.top} corresponds to the 9778 the top left corner of the cropped RAW frame and 9779 {android.sensor.info.preCorrectionActiveArraySize.right, 9780 android.sensor.info.preCorrectionActiveArraySize.bottom} corresponds to 9781 the bottom right corner. Client applications must use the values of the keys 9782 in the CaptureResult metadata if present. 9783 9784 Crop regions android.scaler.cropRegion, AE/AWB/AF regions and face coordinates still 9785 use the android.sensor.info.activeArraySize coordinate system as usual. 9786 </details> 9787 </entry> 9788 </dynamic> 9789 </section> 9790 <section name="sensor"> 9791 <controls> 9792 <entry name="exposureTime" type="int64" visibility="public" hwlevel="full"> 9793 <description>Duration each pixel is exposed to 9794 light.</description> 9795 <units>Nanoseconds</units> 9796 <range>android.sensor.info.exposureTimeRange</range> 9797 <details>If the sensor can't expose this exact duration, it will shorten the 9798 duration exposed to the nearest possible value (rather than expose longer). 9799 The final exposure time used will be available in the output capture result. 9800 9801 This control is only effective if android.control.aeMode or android.control.mode is set to 9802 OFF; otherwise the auto-exposure algorithm will override this value. However, in the 9803 case that android.control.aePriorityMode is set to SENSOR_EXPOSURE_TIME_PRIORITY, this 9804 control will be effective and not controlled by the auto-exposure algorithm. 9805 </details> 9806 <tag id="V1" /> 9807 </entry> 9808 <entry name="frameDuration" type="int64" visibility="public" hwlevel="full"> 9809 <description>Duration from start of frame readout to 9810 start of next frame readout.</description> 9811 <units>Nanoseconds</units> 9812 <range>See android.sensor.info.maxFrameDuration, {@link 9813 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS}. 9814 The duration is capped to `max(duration, exposureTime + overhead)`.</range> 9815 <details> 9816 The maximum frame rate that can be supported by a camera subsystem is 9817 a function of many factors: 9818 9819 * Requested resolutions of output image streams 9820 * Availability of binning / skipping modes on the imager 9821 * The bandwidth of the imager interface 9822 * The bandwidth of the various ISP processing blocks 9823 9824 Since these factors can vary greatly between different ISPs and 9825 sensors, the camera abstraction tries to represent the bandwidth 9826 restrictions with as simple a model as possible. 9827 9828 The model presented has the following characteristics: 9829 9830 * The image sensor is always configured to output the smallest 9831 resolution possible given the application's requested output stream 9832 sizes. The smallest resolution is defined as being at least as large 9833 as the largest requested output stream size; the camera pipeline must 9834 never digitally upsample sensor data when the crop region covers the 9835 whole sensor. In general, this means that if only small output stream 9836 resolutions are configured, the sensor can provide a higher frame 9837 rate. 9838 * Since any request may use any or all the currently configured 9839 output streams, the sensor and ISP must be configured to support 9840 scaling a single capture to all the streams at the same time. This 9841 means the camera pipeline must be ready to produce the largest 9842 requested output size without any delay. Therefore, the overall 9843 frame rate of a given configured stream set is governed only by the 9844 largest requested stream resolution. 9845 * Using more than one output stream in a request does not affect the 9846 frame duration. 9847 * Certain format-streams may need to do additional background processing 9848 before data is consumed/produced by that stream. These processors 9849 can run concurrently to the rest of the camera pipeline, but 9850 cannot process more than 1 capture at a time. 9851 9852 The necessary information for the application, given the model above, is provided via 9853 {@link 9854 android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS}. 9855 These are used to determine the maximum frame rate / minimum frame duration that is 9856 possible for a given stream configuration. 9857 9858 Specifically, the application can use the following rules to 9859 determine the minimum frame duration it can request from the camera 9860 device: 9861 9862 1. Let the set of currently configured input/output streams be called `S`. 9863 1. Find the minimum frame durations for each stream in `S`, by looking it up in {@link 9864 android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS} 9865 (with its respective size/format). Let this set of frame durations be called `F`. 9866 1. For any given request `R`, the minimum frame duration allowed for `R` is the maximum 9867 out of all values in `F`. Let the streams used in `R` be called `S_r`. 9868 9869 If none of the streams in `S_r` have a stall time (listed in {@link 9870 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration|ACAMERA_SCALER_AVAILABLE_STALL_DURATIONS} 9871 using its respective size/format), then the frame duration in `F` determines the steady 9872 state frame rate that the application will get if it uses `R` as a repeating request. Let 9873 this special kind of request be called `Rsimple`. 9874 9875 A repeating request `Rsimple` can be _occasionally_ interleaved by a single capture of a 9876 new request `Rstall` (which has at least one in-use stream with a non-0 stall time) and if 9877 `Rstall` has the same minimum frame duration this will not cause a frame rate loss if all 9878 buffers from the previous `Rstall` have already been delivered. 9879 9880 For more details about stalling, see {@link 9881 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration|ACAMERA_SCALER_AVAILABLE_STALL_DURATIONS}. 9882 9883 This control is only effective if android.control.aeMode or android.control.mode is set to 9884 OFF; otherwise the auto-exposure algorithm will override this value. 9885 9886 *Note:* Prior to Android 13, this field was described as measuring the duration from 9887 start of frame exposure to start of next frame exposure, which doesn't reflect the 9888 definition from sensor manufacturer. A mobile sensor defines the frame duration as 9889 intervals between sensor readouts. 9890 </details> 9891 <hal_details> 9892 For more details about stalling, see 9893 android.scaler.availableStallDurations. 9894 </hal_details> 9895 <tag id="V1" /> 9896 </entry> 9897 <entry name="sensitivity" type="int32" visibility="public" hwlevel="full"> 9898 <description>The amount of gain applied to sensor data 9899 before processing.</description> 9900 <units>ISO arithmetic units</units> 9901 <range>android.sensor.info.sensitivityRange</range> 9902 <details> 9903 The sensitivity is the standard ISO sensitivity value, 9904 as defined in ISO 12232:2006. 9905 9906 The sensitivity must be within android.sensor.info.sensitivityRange, and 9907 if if it less than android.sensor.maxAnalogSensitivity, the camera device 9908 is guaranteed to use only analog amplification for applying the gain. 9909 9910 If the camera device cannot apply the exact sensitivity 9911 requested, it will reduce the gain to the nearest supported 9912 value. The final sensitivity used will be available in the 9913 output capture result. 9914 9915 This control is only effective if android.control.aeMode or android.control.mode is set to 9916 OFF; otherwise the auto-exposure algorithm will override this value. However, in the 9917 case that android.control.aePriorityMode is set to SENSOR_SENSITIVITY_PRIORITY, this 9918 control will be effective and not controlled by the auto-exposure algorithm. 9919 9920 Note that for devices supporting postRawSensitivityBoost, the total sensitivity applied 9921 to the final processed image is the combination of android.sensor.sensitivity and 9922 android.control.postRawSensitivityBoost. In case the application uses the sensor 9923 sensitivity from last capture result of an auto request for a manual request, in order 9924 to achieve the same brightness in the output image, the application should also 9925 set postRawSensitivityBoost. 9926 </details> 9927 <hal_details>ISO 12232:2006 REI method is acceptable.</hal_details> 9928 <tag id="V1" /> 9929 </entry> 9930 </controls> 9931 <static> 9932 <namespace name="info"> 9933 <entry name="activeArraySize" type="int32" visibility="public" 9934 type_notes="Four ints defining the active pixel rectangle" 9935 container="array" typedef="rectangle" hwlevel="legacy"> 9936 <array> 9937 <size>4</size> 9938 </array> 9939 <description> 9940 The area of the image sensor which corresponds to active pixels after any geometric 9941 distortion correction has been applied. 9942 </description> 9943 <units>Pixel coordinates on the image sensor</units> 9944 <details> 9945 This is the rectangle representing the size of the active region of the sensor (i.e. 9946 the region that actually receives light from the scene) after any geometric correction 9947 has been applied, and should be treated as the maximum size in pixels of any of the 9948 image output formats aside from the raw formats. 9949 9950 This rectangle is defined relative to the full pixel array; (0,0) is the top-left of 9951 the full pixel array, and the size of the full pixel array is given by 9952 android.sensor.info.pixelArraySize. 9953 9954 The coordinate system for most other keys that list pixel coordinates, including 9955 android.scaler.cropRegion, is defined relative to the active array rectangle given in 9956 this field, with `(0, 0)` being the top-left of this rectangle. 9957 9958 The active array may be smaller than the full pixel array, since the full array may 9959 include black calibration pixels or other inactive regions. 9960 9961 For devices that do not support android.distortionCorrection.mode control, the active 9962 array must be the same as android.sensor.info.preCorrectionActiveArraySize. 9963 9964 For devices that support android.distortionCorrection.mode control, the active array must 9965 be enclosed by android.sensor.info.preCorrectionActiveArraySize. The difference between 9966 pre-correction active array and active array accounts for scaling or cropping caused 9967 by lens geometric distortion correction. 9968 9969 In general, application should always refer to active array size for controls like 9970 metering regions or crop region. Two exceptions are when the application is dealing with 9971 RAW image buffers (RAW_SENSOR, RAW10, RAW12 etc), or when application explicitly set 9972 android.distortionCorrection.mode to OFF. In these cases, application should refer 9973 to android.sensor.info.preCorrectionActiveArraySize. 9974 </details> 9975 <ndk_details> 9976 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 9977 </ndk_details> 9978 <hal_details> 9979 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 9980 &gt;= `(0,0)`. 9981 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySize`. 9982 </hal_details> 9983 <tag id="RAW" /> 9984 </entry> 9985 <entry name="sensitivityRange" type="int32" visibility="public" 9986 type_notes="Range of supported sensitivities" 9987 container="array" typedef="rangeInt" 9988 hwlevel="full"> 9989 <array> 9990 <size>2</size> 9991 </array> 9992 <description>Range of sensitivities for android.sensor.sensitivity supported by this 9993 camera device.</description> 9994 <range>Min <= 100, Max &gt;= 800</range> 9995 <details> 9996 The values are the standard ISO sensitivity values, 9997 as defined in ISO 12232:2006. 9998 </details> 9999 10000 <tag id="BC" /> 10001 <tag id="V1" /> 10002 </entry> 10003 <entry name="colorFilterArrangement" type="byte" visibility="public" enum="true" 10004 hwlevel="full"> 10005 <enum> 10006 <value>RGGB</value> 10007 <value>GRBG</value> 10008 <value>GBRG</value> 10009 <value>BGGR</value> 10010 <value>RGB 10011 <notes>Sensor is not Bayer; output has 3 16-bit 10012 values for each pixel, instead of just 1 16-bit value 10013 per pixel.</notes></value> 10014 <value hal_version="3.4">MONO 10015 <notes>Sensor doesn't have any Bayer color filter. 10016 Such sensor captures visible light in monochrome. The exact weighting and 10017 wavelengths captured is not specified, but generally only includes the visible 10018 frequencies. This value implies a MONOCHROME camera.</notes></value> 10019 <value hal_version="3.4">NIR 10020 <notes>Sensor has a near infrared filter capturing light with wavelength between 10021 roughly 750nm and 1400nm, and the same filter covers the whole sensor array. This 10022 value implies a MONOCHROME camera.</notes></value> 10023 </enum> 10024 <description>The arrangement of color filters on sensor; 10025 represents the colors in the top-left 2x2 section of 10026 the sensor, in reading order, for a Bayer camera, or the 10027 light spectrum it captures for MONOCHROME camera. 10028 </description> 10029 <hal_details> 10030 Starting from Android Q, the colorFilterArrangement for a MONOCHROME camera must be 10031 single color patterns, such as MONO or NIR. 10032 </hal_details> 10033 <tag id="RAW" /> 10034 </entry> 10035 <entry name="exposureTimeRange" type="int64" visibility="public" 10036 type_notes="nanoseconds" container="array" typedef="rangeLong" 10037 hwlevel="full"> 10038 <array> 10039 <size>2</size> 10040 </array> 10041 <description>The range of image exposure times for android.sensor.exposureTime supported 10042 by this camera device. 10043 </description> 10044 <units>Nanoseconds</units> 10045 <range>The minimum exposure time will be less than 100 us. For FULL 10046 capability devices (android.info.supportedHardwareLevel == FULL), 10047 the maximum exposure time will be greater than 100ms.</range> 10048 <hal_details>For FULL capability devices (android.info.supportedHardwareLevel == FULL), 10049 The maximum of the range SHOULD be at least 1 second (1e9), MUST be at least 10050 100ms. 10051 </hal_details> 10052 <tag id="V1" /> 10053 </entry> 10054 <entry name="maxFrameDuration" type="int64" visibility="public" 10055 hwlevel="full"> 10056 <description>The maximum possible frame duration (minimum frame rate) for 10057 android.sensor.frameDuration that is supported this camera device.</description> 10058 <units>Nanoseconds</units> 10059 <range>For FULL capability devices 10060 (android.info.supportedHardwareLevel == FULL), at least 100ms. 10061 </range> 10062 <details>Attempting to use frame durations beyond the maximum will result in the frame 10063 duration being clipped to the maximum. See that control for a full definition of frame 10064 durations. 10065 10066 Refer to {@link 10067 android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS} 10068 for the minimum frame duration values. 10069 </details> 10070 <hal_details> 10071 For FULL capability devices (android.info.supportedHardwareLevel == FULL), 10072 The maximum of the range SHOULD be at least 10073 1 second (1e9), MUST be at least 100ms (100e6). 10074 10075 android.sensor.info.maxFrameDuration must be greater or 10076 equal to the android.sensor.info.exposureTimeRange max 10077 value (since exposure time overrides frame duration). 10078 10079 Available minimum frame durations for JPEG must be no greater 10080 than that of the YUV_420_888/IMPLEMENTATION_DEFINED 10081 minimum frame durations (for that respective size). 10082 10083 Since JPEG processing is considered offline and can take longer than 10084 a single uncompressed capture, refer to 10085 android.scaler.availableStallDurations 10086 for details about encoding this scenario. 10087 </hal_details> 10088 <tag id="V1" /> 10089 </entry> 10090 <entry name="physicalSize" type="float" visibility="public" 10091 type_notes="width x height" 10092 container="array" typedef="sizeF" hwlevel="legacy"> 10093 <array> 10094 <size>2</size> 10095 </array> 10096 <description>The physical dimensions of the full pixel 10097 array.</description> 10098 <units>Millimeters</units> 10099 <details>This is the physical size of the sensor pixel 10100 array defined by android.sensor.info.pixelArraySize. 10101 </details> 10102 <hal_details>Needed for FOV calculation for old API</hal_details> 10103 <tag id="V1" /> 10104 <tag id="BC" /> 10105 </entry> 10106 <entry name="pixelArraySize" type="int32" visibility="public" 10107 container="array" typedef="size" hwlevel="legacy"> 10108 <array> 10109 <size>2</size> 10110 </array> 10111 <description>Dimensions of the full pixel array, possibly 10112 including black calibration pixels.</description> 10113 <units>Pixels</units> 10114 <details>The pixel count of the full pixel array of the image sensor, which covers 10115 android.sensor.info.physicalSize area. This represents the full pixel dimensions of 10116 the raw buffers produced by this sensor. 10117 10118 If a camera device supports raw sensor formats, either this or 10119 android.sensor.info.preCorrectionActiveArraySize is the maximum dimensions for the raw 10120 output formats listed in {@link 10121 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 10122 (this depends on whether or not the image sensor returns buffers containing pixels that 10123 are not part of the active array region for blacklevel calibration or other purposes). 10124 10125 Some parts of the full pixel array may not receive light from the scene, 10126 or be otherwise inactive. The android.sensor.info.preCorrectionActiveArraySize key 10127 defines the rectangle of active pixels that will be included in processed image 10128 formats. 10129 </details> 10130 <tag id="RAW" /> 10131 <tag id="BC" /> 10132 </entry> 10133 <entry name="whiteLevel" type="int32" visibility="public"> 10134 <description> 10135 Maximum raw value output by sensor. 10136 </description> 10137 <range>&gt; 255 (8-bit output)</range> 10138 <details> 10139 This specifies the fully-saturated encoding level for the raw 10140 sample values from the sensor. This is typically caused by the 10141 sensor becoming highly non-linear or clipping. The minimum for 10142 each channel is specified by the offset in the 10143 android.sensor.blackLevelPattern key. 10144 10145 The white level is typically determined either by sensor bit depth 10146 (8-14 bits is expected), or by the point where the sensor response 10147 becomes too non-linear to be useful. The default value for this is 10148 maximum representable value for a 16-bit raw sample (2^16 - 1). 10149 10150 The white level values of captured images may vary for different 10151 capture settings (e.g., android.sensor.sensitivity). This key 10152 represents a coarse approximation for such case. It is recommended 10153 to use android.sensor.dynamicWhiteLevel for captures when supported 10154 by the camera device, which provides more accurate white level values. 10155 </details> 10156 <hal_details> 10157 The full bit depth of the sensor must be available in the raw data, 10158 so the value for linear sensors should not be significantly lower 10159 than maximum raw value supported, i.e. 2^(sensor bits per pixel). 10160 </hal_details> 10161 <tag id="RAW" /> 10162 </entry> 10163 <entry name="timestampSource" type="byte" visibility="public" 10164 enum="true" hwlevel="legacy"> 10165 <enum> 10166 <value>UNKNOWN 10167 <notes> 10168 Timestamps from android.sensor.timestamp are in nanoseconds and monotonic, but can 10169 not be compared to timestamps from other subsystems (e.g. accelerometer, gyro etc.), 10170 or other instances of the same or different camera devices in the same system with 10171 accuracy. However, the timestamps are roughly in the same timebase as 10172 {@link android.os.SystemClock#uptimeMillis}. The accuracy is sufficient for tasks 10173 like A/V synchronization for video recording, at least, and the timestamps can be 10174 directly used together with timestamps from the audio subsystem for that task. 10175 10176 Timestamps between streams and results for a single camera instance are comparable, 10177 and the timestamps for all buffers and the result metadata generated by a single 10178 capture are identical. 10179 </notes> 10180 </value> 10181 <value>REALTIME 10182 <notes> 10183 Timestamps from android.sensor.timestamp are in the same timebase as 10184 {@link android.os.SystemClock#elapsedRealtimeNanos}, 10185 and they can be compared to other timestamps using that base. 10186 10187 When buffers from a REALTIME device are passed directly to a video encoder from the 10188 camera, automatic compensation is done to account for differing timebases of the 10189 audio and camera subsystems. If the application is receiving buffers and then later 10190 sending them to a video encoder or other application where they are compared with 10191 audio subsystem timestamps or similar, this compensation is not present. In those 10192 cases, applications need to adjust the timestamps themselves. Since {@link 10193 android.os.SystemClock#elapsedRealtimeNanos} and {@link 10194 android.os.SystemClock#uptimeMillis} only diverge while the device is asleep, an 10195 offset between the two sources can be measured once per active session and applied 10196 to timestamps for sufficient accuracy for A/V sync. 10197 </notes> 10198 </value> 10199 </enum> 10200 <description>The time base source for sensor capture start timestamps.</description> 10201 <details> 10202 The timestamps provided for captures are always in nanoseconds and monotonic, but 10203 may not based on a time source that can be compared to other system time sources. 10204 10205 This characteristic defines the source for the timestamps, and therefore whether they 10206 can be compared against other system time sources/timestamps. 10207 </details> 10208 <hal_details> 10209 For camera devices implement UNKNOWN, the camera framework expects that the timestamp 10210 source to be SYSTEM_TIME_MONOTONIC. For camera devices implement REALTIME, the camera 10211 framework expects that the timestamp source to be SYSTEM_TIME_BOOTTIME. See 10212 system/core/include/utils/Timers.h for the definition of SYSTEM_TIME_MONOTONIC and 10213 SYSTEM_TIME_BOOTTIME. Note that HAL must follow above expectation; otherwise video 10214 recording might suffer unexpected behavior. 10215 10216 Also, camera devices which implement REALTIME must pass the ITS sensor fusion test which 10217 tests the alignment between camera timestamps and gyro sensor timestamps. 10218 </hal_details> 10219 <tag id="V1" /> 10220 </entry> 10221 <entry name="lensShadingApplied" type="byte" visibility="public" enum="true" 10222 typedef="boolean"> 10223 <enum> 10224 <value>FALSE</value> 10225 <value>TRUE</value> 10226 </enum> 10227 <description>Whether the RAW images output from this camera device are subject to 10228 lens shading correction.</description> 10229 <details> 10230 If `true`, all images produced by the camera device in the `RAW` image formats will have 10231 at least some lens shading correction already applied to it. If `false`, the images will 10232 not be adjusted for lens shading correction. See android.request.maxNumOutputRaw for a 10233 list of RAW image formats. 10234 10235 When `true`, the `lensShadingCorrectionMap` key may still have values greater than 1.0, 10236 and those will need to be applied to any captured RAW frames for them to match the shading 10237 correction of processed buffers such as `YUV` or `JPEG` images. This may occur, for 10238 example, when some basic fixed lens shading correction is applied by hardware to RAW data, 10239 and additional correction is done dynamically in the camera processing pipeline after 10240 demosaicing. 10241 10242 This key will be `null` for all devices do not report this information. 10243 Devices with RAW capability will always report this information in this key. 10244 </details> 10245 </entry> 10246 <entry name="preCorrectionActiveArraySize" type="int32" visibility="public" 10247 type_notes="Four ints defining the active pixel rectangle" container="array" 10248 typedef="rectangle" hwlevel="legacy"> 10249 <array> 10250 <size>4</size> 10251 </array> 10252 <description> 10253 The area of the image sensor which corresponds to active pixels prior to the 10254 application of any geometric distortion correction. 10255 </description> 10256 <units>Pixel coordinates on the image sensor</units> 10257 <details> 10258 This is the rectangle representing the size of the active region of the sensor (i.e. 10259 the region that actually receives light from the scene) before any geometric correction 10260 has been applied, and should be treated as the active region rectangle for any of the 10261 raw formats. All metadata associated with raw processing (e.g. the lens shading 10262 correction map, and radial distortion fields) treats the top, left of this rectangle as 10263 the origin, (0,0). 10264 10265 The size of this region determines the maximum field of view and the maximum number of 10266 pixels that an image from this sensor can contain, prior to the application of 10267 geometric distortion correction. The effective maximum pixel dimensions of a 10268 post-distortion-corrected image is given by the android.sensor.info.activeArraySize 10269 field, and the effective maximum field of view for a post-distortion-corrected image 10270 can be calculated by applying the geometric distortion correction fields to this 10271 rectangle, and cropping to the rectangle given in android.sensor.info.activeArraySize. 10272 10273 E.g. to calculate position of a pixel, (x,y), in a processed YUV output image with the 10274 dimensions in android.sensor.info.activeArraySize given the position of a pixel, 10275 (x', y'), in the raw pixel array with dimensions given in 10276 android.sensor.info.pixelArraySize: 10277 10278 1. Choose a pixel (x', y') within the active array region of the raw buffer given in 10279 android.sensor.info.preCorrectionActiveArraySize, otherwise this pixel is considered 10280 to be outside of the FOV, and will not be shown in the processed output image. 10281 1. Apply geometric distortion correction to get the post-distortion pixel coordinate, 10282 (x_i, y_i). When applying geometric correction metadata, note that metadata for raw 10283 buffers is defined relative to the top, left of the 10284 android.sensor.info.preCorrectionActiveArraySize rectangle. 10285 1. If the resulting corrected pixel coordinate is within the region given in 10286 android.sensor.info.activeArraySize, then the position of this pixel in the 10287 processed output image buffer is `(x_i - activeArray.left, y_i - activeArray.top)`, 10288 when the top, left coordinate of that buffer is treated as (0, 0). 10289 10290 Thus, for pixel x',y' = (25, 25) on a sensor where android.sensor.info.pixelArraySize 10291 is (100,100), android.sensor.info.preCorrectionActiveArraySize is (10, 10, 100, 100), 10292 android.sensor.info.activeArraySize is (20, 20, 80, 80), and the geometric distortion 10293 correction doesn't change the pixel coordinate, the resulting pixel selected in 10294 pixel coordinates would be x,y = (25, 25) relative to the top,left of the raw buffer 10295 with dimensions given in android.sensor.info.pixelArraySize, and would be (5, 5) 10296 relative to the top,left of post-processed YUV output buffer with dimensions given in 10297 android.sensor.info.activeArraySize. 10298 10299 The currently supported fields that correct for geometric distortion are: 10300 10301 1. android.lens.distortion. 10302 10303 If the camera device doesn't support geometric distortion correction, or all of the 10304 geometric distortion fields are no-ops, this rectangle will be the same as the 10305 post-distortion-corrected rectangle given in android.sensor.info.activeArraySize. 10306 10307 This rectangle is defined relative to the full pixel array; (0,0) is the top-left of 10308 the full pixel array, and the size of the full pixel array is given by 10309 android.sensor.info.pixelArraySize. 10310 10311 The pre-correction active array may be smaller than the full pixel array, since the 10312 full array may include black calibration pixels or other inactive regions. 10313 </details> 10314 <ndk_details> 10315 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 10316 </ndk_details> 10317 <hal_details> 10318 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 10319 &gt;= `(0,0)`. 10320 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySize`. 10321 10322 If omitted by the HAL implementation, the camera framework will assume that this is 10323 the same as the post-correction active array region given in 10324 android.sensor.info.activeArraySize. 10325 </hal_details> 10326 <tag id="RAW" /> 10327 </entry> 10328 <entry name="activeArraySizeMaximumResolution" type="int32" visibility="public" 10329 type_notes="Four ints defining the active pixel rectangle" 10330 container="array" typedef="rectangle" hal_version="3.6"> 10331 <array> 10332 <size>4</size> 10333 </array> 10334 <description> 10335 The area of the image sensor which corresponds to active pixels after any geometric 10336 distortion correction has been applied, when the sensor runs in maximum resolution mode. 10337 </description> 10338 <units>Pixel coordinates on the image sensor</units> 10339 <details> 10340 Analogous to android.sensor.info.activeArraySize, when android.sensor.pixelMode 10341 is set to 10342 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10343 Refer to android.sensor.info.activeArraySize for details, with sensor array related keys 10344 replaced with their 10345 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 10346 counterparts. 10347 This key will only be present for devices which advertise the 10348 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10349 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 10350 lists android.sensor.pixelMode. 10351 </details> 10352 <ndk_details> 10353 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 10354 </ndk_details> 10355 <hal_details> 10356 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 10357 &gt;= `(0,0)`. 10358 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySizeMaximumResolution`. 10359 </hal_details> 10360 <tag id="RAW" /> 10361 </entry> 10362 <entry name="pixelArraySizeMaximumResolution" type="int32" visibility="public" 10363 container="array" typedef="size" hal_version="3.6"> 10364 <array> 10365 <size>2</size> 10366 </array> 10367 <description>Dimensions of the full pixel array, possibly 10368 including black calibration pixels, when the sensor runs in maximum resolution mode. 10369 Analogous to android.sensor.info.pixelArraySize, when android.sensor.pixelMode is 10370 set to 10371 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10372 </description> 10373 <units>Pixels</units> 10374 <details> 10375 The pixel count of the full pixel array of the image sensor, which covers 10376 android.sensor.info.physicalSize area. This represents the full pixel dimensions of 10377 the raw buffers produced by this sensor, when it runs in maximum resolution mode. That 10378 is, when android.sensor.pixelMode is set to 10379 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10380 This key will only be present for devices which advertise the 10381 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10382 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 10383 lists android.sensor.pixelMode. 10384 </details> 10385 <tag id="RAW" /> 10386 </entry> 10387 <entry name="preCorrectionActiveArraySizeMaximumResolution" type="int32" 10388 visibility="public" type_notes="Four ints defining the active pixel rectangle" 10389 container="array" typedef="rectangle" hal_version="3.6"> 10390 <array> 10391 <size>4</size> 10392 </array> 10393 <description> 10394 The area of the image sensor which corresponds to active pixels prior to the 10395 application of any geometric distortion correction, when the sensor runs in maximum 10396 resolution mode. This key must be used for crop / metering regions, only when 10397 android.sensor.pixelMode is set to 10398 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10399 </description> 10400 <units>Pixel coordinates on the image sensor</units> 10401 <details> 10402 Analogous to android.sensor.info.preCorrectionActiveArraySize, 10403 when android.sensor.pixelMode is set to 10404 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10405 This key will only be present for devices which advertise the 10406 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10407 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 10408 lists android.sensor.pixelMode. 10409 </details> 10410 <ndk_details> 10411 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 10412 </ndk_details> 10413 <hal_details> 10414 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 10415 &gt;= `(0,0)`. 10416 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySizeMaximumResolution`. 10417 10418 If omitted by the HAL implementation, the camera framework will assume that this is 10419 the same as the post-correction active array region given in 10420 android.sensor.info.activeArraySizeMaximumResolution. 10421 </hal_details> 10422 <tag id="RAW" /> 10423 </entry> 10424 <entry name="binningFactor" type="int32" visibility="public" 10425 container="array" typedef="size" hal_version="3.6"> 10426 <array> 10427 <size>2</size> 10428 </array> 10429 <description> Dimensions of the group of pixels which are under the same color filter. 10430 This specifies the width and height (pair of integers) of the group of pixels which fall 10431 under the same color filter for ULTRA_HIGH_RESOLUTION sensors. 10432 </description> 10433 <units>Pixels</units> 10434 <details> Sensors can have pixels grouped together under the same color filter in order 10435 to improve various aspects of imaging such as noise reduction, low light 10436 performance etc. These groups can be of various sizes such as 2X2 (quad bayer), 10437 3X3 (nona-bayer). This key specifies the length and width of the pixels grouped under 10438 the same color filter. 10439 In case the device has the 10440 {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10441 capability : 10442 10443 * This key will not be present if REMOSAIC_REPROCESSING is not supported, since RAW 10444 images will have a regular bayer pattern. 10445 10446 In case the device does not have the 10447 {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10448 capability : 10449 10450 * This key will be present if 10451 {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 10452 lists android.sensor.pixelMode, since RAW 10453 images may not necessarily have a regular bayer pattern when 10454 {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode} is set to 10455 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10456 </details> 10457 </entry> 10458 </namespace> 10459 <entry name="referenceIlluminant1" type="byte" visibility="public" 10460 enum="true" permission_needed="true" > 10461 <enum> 10462 <value id="1">DAYLIGHT</value> 10463 <value id="2">FLUORESCENT</value> 10464 <value id="3">TUNGSTEN 10465 <notes>Incandescent light</notes> 10466 </value> 10467 <value id="4">FLASH</value> 10468 <value id="9">FINE_WEATHER</value> 10469 <value id="10">CLOUDY_WEATHER</value> 10470 <value id="11">SHADE</value> 10471 <value id="12">DAYLIGHT_FLUORESCENT 10472 <notes>D 5700 - 7100K</notes> 10473 </value> 10474 <value id="13">DAY_WHITE_FLUORESCENT 10475 <notes>N 4600 - 5400K</notes> 10476 </value> 10477 <value id="14">COOL_WHITE_FLUORESCENT 10478 <notes>W 3900 - 4500K</notes> 10479 </value> 10480 <value id="15">WHITE_FLUORESCENT 10481 <notes>WW 3200 - 3700K</notes> 10482 </value> 10483 <value id="17">STANDARD_A</value> 10484 <value id="18">STANDARD_B</value> 10485 <value id="19">STANDARD_C</value> 10486 <value id="20">D55</value> 10487 <value id="21">D65</value> 10488 <value id="22">D75</value> 10489 <value id="23">D50</value> 10490 <value id="24">ISO_STUDIO_TUNGSTEN</value> 10491 </enum> 10492 <description> 10493 The standard reference illuminant used as the scene light source when 10494 calculating the android.sensor.colorTransform1, 10495 android.sensor.calibrationTransform1, and 10496 android.sensor.forwardMatrix1 matrices. 10497 </description> 10498 <details> 10499 The values in this key correspond to the values defined for the 10500 EXIF LightSource tag. These illuminants are standard light sources 10501 that are often used calibrating camera devices. 10502 10503 If this key is present, then android.sensor.colorTransform1, 10504 android.sensor.calibrationTransform1, and 10505 android.sensor.forwardMatrix1 will also be present. 10506 10507 Some devices may choose to provide a second set of calibration 10508 information for improved quality, including 10509 android.sensor.referenceIlluminant2 and its corresponding matrices. 10510 10511 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10512 the camera device has RAW capability. 10513 </details> 10514 <hal_details> 10515 The first reference illuminant (android.sensor.referenceIlluminant1) 10516 and corresponding matrices must be present to support the RAW capability 10517 and DNG output. 10518 10519 When producing raw images with a color profile that has only been 10520 calibrated against a single light source, it is valid to omit 10521 android.sensor.referenceIlluminant2 along with the 10522 android.sensor.colorTransform2, android.sensor.calibrationTransform2, 10523 and android.sensor.forwardMatrix2 matrices. 10524 10525 If only android.sensor.referenceIlluminant1 is included, it should be 10526 chosen so that it is representative of typical scene lighting. In 10527 general, D50 or DAYLIGHT will be chosen for this case. 10528 10529 If both android.sensor.referenceIlluminant1 and 10530 android.sensor.referenceIlluminant2 are included, they should be 10531 chosen to represent the typical range of scene lighting conditions. 10532 In general, low color temperature illuminant such as Standard-A will 10533 be chosen for the first reference illuminant and a higher color 10534 temperature illuminant such as D65 will be chosen for the second 10535 reference illuminant. 10536 </hal_details> 10537 <tag id="RAW" /> 10538 </entry> 10539 <entry name="referenceIlluminant2" type="byte" visibility="public" 10540 permission_needed="true" > 10541 <description> 10542 The standard reference illuminant used as the scene light source when 10543 calculating the android.sensor.colorTransform2, 10544 android.sensor.calibrationTransform2, and 10545 android.sensor.forwardMatrix2 matrices. 10546 </description> 10547 <range>Any value listed in android.sensor.referenceIlluminant1</range> 10548 <details> 10549 See android.sensor.referenceIlluminant1 for more details. 10550 10551 If this key is present, then android.sensor.colorTransform2, 10552 android.sensor.calibrationTransform2, and 10553 android.sensor.forwardMatrix2 will also be present. 10554 10555 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10556 the camera device has RAW capability. 10557 </details> 10558 <tag id="RAW" /> 10559 </entry> 10560 <entry name="calibrationTransform1" type="rational" 10561 visibility="public" optional="true" 10562 type_notes="3x3 matrix in row-major-order" container="array" 10563 typedef="colorSpaceTransform" permission_needed="true" > 10564 <array> 10565 <size>3</size> 10566 <size>3</size> 10567 </array> 10568 <description> 10569 A per-device calibration transform matrix that maps from the 10570 reference sensor colorspace to the actual device sensor colorspace. 10571 </description> 10572 <details> 10573 This matrix is used to correct for per-device variations in the 10574 sensor colorspace, and is used for processing raw buffer data. 10575 10576 The matrix is expressed as a 3x3 matrix in row-major-order, and 10577 contains a per-device calibration transform that maps colors 10578 from reference sensor color space (i.e. the "golden module" 10579 colorspace) into this camera device's native sensor color 10580 space under the first reference illuminant 10581 (android.sensor.referenceIlluminant1). 10582 10583 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10584 the camera device has RAW capability. 10585 </details> 10586 <tag id="RAW" /> 10587 </entry> 10588 <entry name="calibrationTransform2" type="rational" 10589 visibility="public" optional="true" 10590 type_notes="3x3 matrix in row-major-order" container="array" 10591 typedef="colorSpaceTransform" permission_needed="true" > 10592 <array> 10593 <size>3</size> 10594 <size>3</size> 10595 </array> 10596 <description> 10597 A per-device calibration transform matrix that maps from the 10598 reference sensor colorspace to the actual device sensor colorspace 10599 (this is the colorspace of the raw buffer data). 10600 </description> 10601 <details> 10602 This matrix is used to correct for per-device variations in the 10603 sensor colorspace, and is used for processing raw buffer data. 10604 10605 The matrix is expressed as a 3x3 matrix in row-major-order, and 10606 contains a per-device calibration transform that maps colors 10607 from reference sensor color space (i.e. the "golden module" 10608 colorspace) into this camera device's native sensor color 10609 space under the second reference illuminant 10610 (android.sensor.referenceIlluminant2). 10611 10612 This matrix will only be present if the second reference 10613 illuminant is present. 10614 10615 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10616 the camera device has RAW capability. 10617 </details> 10618 <tag id="RAW" /> 10619 </entry> 10620 <entry name="colorTransform1" type="rational" 10621 visibility="public" optional="true" 10622 type_notes="3x3 matrix in row-major-order" container="array" 10623 typedef="colorSpaceTransform" permission_needed="true" > 10624 <array> 10625 <size>3</size> 10626 <size>3</size> 10627 </array> 10628 <description> 10629 A matrix that transforms color values from CIE XYZ color space to 10630 reference sensor color space. 10631 </description> 10632 <details> 10633 This matrix is used to convert from the standard CIE XYZ color 10634 space to the reference sensor colorspace, and is used when processing 10635 raw buffer data. 10636 10637 The matrix is expressed as a 3x3 matrix in row-major-order, and 10638 contains a color transform matrix that maps colors from the CIE 10639 XYZ color space to the reference sensor color space (i.e. the 10640 "golden module" colorspace) under the first reference illuminant 10641 (android.sensor.referenceIlluminant1). 10642 10643 The white points chosen in both the reference sensor color space 10644 and the CIE XYZ colorspace when calculating this transform will 10645 match the standard white point for the first reference illuminant 10646 (i.e. no chromatic adaptation will be applied by this transform). 10647 10648 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10649 the camera device has RAW capability. 10650 </details> 10651 <tag id="RAW" /> 10652 </entry> 10653 <entry name="colorTransform2" type="rational" 10654 visibility="public" optional="true" 10655 type_notes="3x3 matrix in row-major-order" container="array" 10656 typedef="colorSpaceTransform" permission_needed="true" > 10657 <array> 10658 <size>3</size> 10659 <size>3</size> 10660 </array> 10661 <description> 10662 A matrix that transforms color values from CIE XYZ color space to 10663 reference sensor color space. 10664 </description> 10665 <details> 10666 This matrix is used to convert from the standard CIE XYZ color 10667 space to the reference sensor colorspace, and is used when processing 10668 raw buffer data. 10669 10670 The matrix is expressed as a 3x3 matrix in row-major-order, and 10671 contains a color transform matrix that maps colors from the CIE 10672 XYZ color space to the reference sensor color space (i.e. the 10673 "golden module" colorspace) under the second reference illuminant 10674 (android.sensor.referenceIlluminant2). 10675 10676 The white points chosen in both the reference sensor color space 10677 and the CIE XYZ colorspace when calculating this transform will 10678 match the standard white point for the second reference illuminant 10679 (i.e. no chromatic adaptation will be applied by this transform). 10680 10681 This matrix will only be present if the second reference 10682 illuminant is present. 10683 10684 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10685 the camera device has RAW capability. 10686 </details> 10687 <tag id="RAW" /> 10688 </entry> 10689 <entry name="forwardMatrix1" type="rational" 10690 visibility="public" optional="true" 10691 type_notes="3x3 matrix in row-major-order" container="array" 10692 typedef="colorSpaceTransform" permission_needed="true" > 10693 <array> 10694 <size>3</size> 10695 <size>3</size> 10696 </array> 10697 <description> 10698 A matrix that transforms white balanced camera colors from the reference 10699 sensor colorspace to the CIE XYZ colorspace with a D50 whitepoint. 10700 </description> 10701 <details> 10702 This matrix is used to convert to the standard CIE XYZ colorspace, and 10703 is used when processing raw buffer data. 10704 10705 This matrix is expressed as a 3x3 matrix in row-major-order, and contains 10706 a color transform matrix that maps white balanced colors from the 10707 reference sensor color space to the CIE XYZ color space with a D50 white 10708 point. 10709 10710 Under the first reference illuminant (android.sensor.referenceIlluminant1) 10711 this matrix is chosen so that the standard white point for this reference 10712 illuminant in the reference sensor colorspace is mapped to D50 in the 10713 CIE XYZ colorspace. 10714 10715 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10716 the camera device has RAW capability. 10717 </details> 10718 <tag id="RAW" /> 10719 </entry> 10720 <entry name="forwardMatrix2" type="rational" 10721 visibility="public" optional="true" 10722 type_notes="3x3 matrix in row-major-order" container="array" 10723 typedef="colorSpaceTransform" permission_needed="true" > 10724 <array> 10725 <size>3</size> 10726 <size>3</size> 10727 </array> 10728 <description> 10729 A matrix that transforms white balanced camera colors from the reference 10730 sensor colorspace to the CIE XYZ colorspace with a D50 whitepoint. 10731 </description> 10732 <details> 10733 This matrix is used to convert to the standard CIE XYZ colorspace, and 10734 is used when processing raw buffer data. 10735 10736 This matrix is expressed as a 3x3 matrix in row-major-order, and contains 10737 a color transform matrix that maps white balanced colors from the 10738 reference sensor color space to the CIE XYZ color space with a D50 white 10739 point. 10740 10741 Under the second reference illuminant (android.sensor.referenceIlluminant2) 10742 this matrix is chosen so that the standard white point for this reference 10743 illuminant in the reference sensor colorspace is mapped to D50 in the 10744 CIE XYZ colorspace. 10745 10746 This matrix will only be present if the second reference 10747 illuminant is present. 10748 10749 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10750 the camera device has RAW capability. 10751 </details> 10752 <tag id="RAW" /> 10753 </entry> 10754 <entry name="baseGainFactor" type="rational" 10755 optional="true"> 10756 <description>Gain factor from electrons to raw units when 10757 ISO=100</description> 10758 <tag id="FUTURE" /> 10759 </entry> 10760 <entry name="blackLevelPattern" type="int32" visibility="public" 10761 optional="true" type_notes="2x2 raw count block" container="array" 10762 typedef="blackLevelPattern"> 10763 <array> 10764 <size>4</size> 10765 </array> 10766 <description> 10767 A fixed black level offset for each of the color filter arrangement 10768 (CFA) mosaic channels. 10769 </description> 10770 <range>&gt;= 0 for each.</range> 10771 <details> 10772 This key specifies the zero light value for each of the CFA mosaic 10773 channels in the camera sensor. The maximal value output by the 10774 sensor is represented by the value in android.sensor.info.whiteLevel. 10775 10776 The values are given in the same order as channels listed for the CFA 10777 layout key (see android.sensor.info.colorFilterArrangement), i.e. the 10778 nth value given corresponds to the black level offset for the nth 10779 color channel listed in the CFA. 10780 10781 The black level values of captured images may vary for different 10782 capture settings (e.g., android.sensor.sensitivity). This key 10783 represents a coarse approximation for such case. It is recommended to 10784 use android.sensor.dynamicBlackLevel or use pixels from 10785 android.sensor.opticalBlackRegions directly for captures when 10786 supported by the camera device, which provides more accurate black 10787 level values. For raw capture in particular, it is recommended to use 10788 pixels from android.sensor.opticalBlackRegions to calculate black 10789 level values for each frame. 10790 10791 For a MONOCHROME camera device, all of the 2x2 channels must have the same values. 10792 </details> 10793 <hal_details> 10794 The values are given in row-column scan order, with the first value 10795 corresponding to the element of the CFA in row=0, column=0. 10796 </hal_details> 10797 <tag id="RAW" /> 10798 </entry> 10799 <entry name="maxAnalogSensitivity" type="int32" visibility="public" 10800 optional="true" hwlevel="full"> 10801 <description>Maximum sensitivity that is implemented 10802 purely through analog gain.</description> 10803 <details>For android.sensor.sensitivity values less than or 10804 equal to this, all applied gain must be analog. For 10805 values above this, the gain applied can be a mix of analog and 10806 digital.</details> 10807 <tag id="V1" /> 10808 <tag id="FULL" /> 10809 </entry> 10810 <entry name="orientation" type="int32" visibility="public" 10811 hwlevel="legacy"> 10812 <description>Clockwise angle through which the output image needs to be rotated to be 10813 upright on the device screen in its native orientation. 10814 </description> 10815 <units>Degrees of clockwise rotation; always a multiple of 10816 90</units> 10817 <range>0, 90, 180, 270</range> 10818 <details> 10819 Also defines the direction of rolling shutter readout, which is from top to bottom in 10820 the sensor's coordinate system. 10821 10822 Starting with Android API level 32, camera clients that query the orientation via 10823 {@link android.hardware.camera2.CameraCharacteristics#get} on foldable devices which 10824 include logical cameras can receive a value that can dynamically change depending on the 10825 device/fold state. 10826 Clients are advised to not cache or store the orientation value of such logical sensors. 10827 In case repeated queries to CameraCharacteristics are not preferred, then clients can 10828 also access the entire mapping from device state to sensor orientation in 10829 {@link android.hardware.camera2.params.DeviceStateSensorOrientationMap}. 10830 Do note that a dynamically changing sensor orientation value in camera characteristics 10831 will not be the best way to establish the orientation per frame. Clients that want to 10832 know the sensor orientation of a particular captured frame should query the 10833 android.logicalMultiCamera.activePhysicalId from the corresponding capture result and 10834 check the respective physical camera orientation. 10835 </details> 10836 <ndk_details> 10837 Native camera clients must query android.info.deviceStateOrientations for the mapping 10838 between device state and camera sensor orientation. Dynamic updates to the sensor 10839 orientation are not supported in this code path. 10840 </ndk_details> 10841 <tag id="BC" /> 10842 </entry> 10843 <entry name="profileHueSatMapDimensions" type="int32" 10844 visibility="system" optional="true" 10845 type_notes="Number of samples for hue, saturation, and value" 10846 container="array"> 10847 <array> 10848 <size>3</size> 10849 </array> 10850 <description> 10851 The number of input samples for each dimension of 10852 android.sensor.profileHueSatMap. 10853 </description> 10854 <range> 10855 Hue &gt;= 1, 10856 Saturation &gt;= 2, 10857 Value &gt;= 1 10858 </range> 10859 <details> 10860 The number of input samples for the hue, saturation, and value 10861 dimension of android.sensor.profileHueSatMap. The order of the 10862 dimensions given is hue, saturation, value; where hue is the 0th 10863 element. 10864 </details> 10865 <tag id="RAW" /> 10866 </entry> 10867 </static> 10868 <dynamic> 10869 <clone entry="android.sensor.exposureTime" kind="controls"> 10870 </clone> 10871 <clone entry="android.sensor.frameDuration" 10872 kind="controls"></clone> 10873 <clone entry="android.sensor.sensitivity" kind="controls"> 10874 </clone> 10875 <entry name="timestamp" type="int64" visibility="public" 10876 hwlevel="legacy"> 10877 <description>Time at start of exposure of first 10878 row of the image sensor active array, in nanoseconds.</description> 10879 <units>Nanoseconds</units> 10880 <range>&gt; 0</range> 10881 <details>The timestamps are also included in all image 10882 buffers produced for the same capture, and will be identical 10883 on all the outputs. 10884 10885 When android.sensor.info.timestampSource `==` UNKNOWN, 10886 the timestamps measure time since an unspecified starting point, 10887 and are monotonically increasing. They can be compared with the 10888 timestamps for other captures from the same camera device, but are 10889 not guaranteed to be comparable to any other time source. 10890 10891 When android.sensor.info.timestampSource `==` REALTIME, the 10892 timestamps measure time in the same timebase as {@link 10893 android.os.SystemClock#elapsedRealtimeNanos}, and they can 10894 be compared to other timestamps from other subsystems that 10895 are using that base. 10896 10897 For reprocessing, the timestamp will match the start of exposure of 10898 the input image, i.e. {@link CaptureResult#SENSOR_TIMESTAMP the 10899 timestamp} in the TotalCaptureResult that was used to create the 10900 reprocess capture request. 10901 </details> 10902 <hal_details> 10903 All timestamps must be in reference to the kernel's 10904 CLOCK_BOOTTIME monotonic clock, which properly accounts for 10905 time spent asleep. This allows for synchronization with 10906 sensors that continue to operate while the system is 10907 otherwise asleep. 10908 10909 If android.sensor.info.timestampSource `==` REALTIME, 10910 The timestamp must be synchronized with the timestamps from other 10911 sensor subsystems that are using the same timebase. 10912 10913 For reprocessing, the input image's start of exposure can be looked up 10914 with android.sensor.timestamp from the metadata included in the 10915 capture request. 10916 </hal_details> 10917 <tag id="BC" /> 10918 </entry> 10919 <entry name="temperature" type="float" 10920 optional="true"> 10921 <description>The temperature of the sensor, sampled at the time 10922 exposure began for this frame. 10923 10924 The thermal diode being queried should be inside the sensor PCB, or 10925 somewhere close to it. 10926 </description> 10927 10928 <units>Celsius</units> 10929 <range>Optional. This value is missing if no temperature is available.</range> 10930 <tag id="FUTURE" /> 10931 </entry> 10932 <entry name="neutralColorPoint" type="rational" visibility="public" 10933 optional="true" container="array"> 10934 <array> 10935 <size>3</size> 10936 </array> 10937 <description> 10938 The estimated camera neutral color in the native sensor colorspace at 10939 the time of capture. 10940 </description> 10941 <details> 10942 This value gives the neutral color point encoded as an RGB value in the 10943 native sensor color space. The neutral color point indicates the 10944 currently estimated white point of the scene illumination. It can be 10945 used to interpolate between the provided color transforms when 10946 processing raw sensor data. 10947 10948 The order of the values is R, G, B; where R is in the lowest index. 10949 10950 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10951 the camera device has RAW capability. 10952 </details> 10953 <tag id="RAW" /> 10954 </entry> 10955 <entry name="noiseProfile" type="double" visibility="public" 10956 optional="true" type_notes="Pairs of noise model coefficients" 10957 container="array" typedef="pairDoubleDouble"> 10958 <array> 10959 <size>2</size> 10960 <size>CFA Channels</size> 10961 </array> 10962 <description> 10963 Noise model coefficients for each CFA mosaic channel. 10964 </description> 10965 <details> 10966 This key contains two noise model coefficients for each CFA channel 10967 corresponding to the sensor amplification (S) and sensor readout 10968 noise (O). These are given as pairs of coefficients for each channel 10969 in the same order as channels listed for the CFA layout key 10970 (see android.sensor.info.colorFilterArrangement). This is 10971 represented as an array of Pair&lt;Double, Double&gt;, where 10972 the first member of the Pair at index n is the S coefficient and the 10973 second member is the O coefficient for the nth color channel in the CFA. 10974 10975 These coefficients are used in a two parameter noise model to describe 10976 the amount of noise present in the image for each CFA channel. The 10977 noise model used here is: 10978 10979 N(x) = sqrt(Sx + O) 10980 10981 Where x represents the recorded signal of a CFA channel normalized to 10982 the range [0, 1], and S and O are the noise model coefficients for 10983 that channel. 10984 10985 A more detailed description of the noise model can be found in the 10986 Adobe DNG specification for the NoiseProfile tag. 10987 10988 For a MONOCHROME camera, there is only one color channel. So the noise model coefficients 10989 will only contain one S and one O. 10990 10991 </details> 10992 <hal_details> 10993 For a CFA layout of RGGB, the list of coefficients would be given as 10994 an array of doubles S0,O0,S1,O1,..., where S0 and O0 are the coefficients 10995 for the red channel, S1 and O1 are the coefficients for the first green 10996 channel, etc. 10997 </hal_details> 10998 <tag id="RAW" /> 10999 </entry> 11000 <entry name="profileHueSatMap" type="float" 11001 visibility="system" optional="true" 11002 type_notes="Mapping for hue, saturation, and value" 11003 container="array"> 11004 <array> 11005 <size>hue_samples</size> 11006 <size>saturation_samples</size> 11007 <size>value_samples</size> 11008 <size>3</size> 11009 </array> 11010 <description> 11011 A mapping containing a hue shift, saturation scale, and value scale 11012 for each pixel. 11013 </description> 11014 <units> 11015 The hue shift is given in degrees; saturation and value scale factors are 11016 unitless and are between 0 and 1 inclusive 11017 </units> 11018 <details> 11019 hue_samples, saturation_samples, and value_samples are given in 11020 android.sensor.profileHueSatMapDimensions. 11021 11022 Each entry of this map contains three floats corresponding to the 11023 hue shift, saturation scale, and value scale, respectively; where the 11024 hue shift has the lowest index. The map entries are stored in the key 11025 in nested loop order, with the value divisions in the outer loop, the 11026 hue divisions in the middle loop, and the saturation divisions in the 11027 inner loop. All zero input saturation entries are required to have a 11028 value scale factor of 1.0. 11029 </details> 11030 <tag id="RAW" /> 11031 </entry> 11032 <entry name="profileToneCurve" type="float" 11033 visibility="system" optional="true" 11034 type_notes="Samples defining a spline for a tone-mapping curve" 11035 container="array"> 11036 <array> 11037 <size>samples</size> 11038 <size>2</size> 11039 </array> 11040 <description> 11041 A list of x,y samples defining a tone-mapping curve for gamma adjustment. 11042 </description> 11043 <range> 11044 Each sample has an input range of `[0, 1]` and an output range of 11045 `[0, 1]`. The first sample is required to be `(0, 0)`, and the last 11046 sample is required to be `(1, 1)`. 11047 </range> 11048 <details> 11049 This key contains a default tone curve that can be applied while 11050 processing the image as a starting point for user adjustments. 11051 The curve is specified as a list of value pairs in linear gamma. 11052 The curve is interpolated using a cubic spline. 11053 </details> 11054 <tag id="RAW" /> 11055 </entry> 11056 <entry name="greenSplit" type="float" visibility="public" optional="true"> 11057 <description> 11058 The worst-case divergence between Bayer green channels. 11059 </description> 11060 <range> 11061 &gt;= 0 11062 </range> 11063 <details> 11064 This value is an estimate of the worst case split between the 11065 Bayer green channels in the red and blue rows in the sensor color 11066 filter array. 11067 11068 The green split is calculated as follows: 11069 11070 1. A 5x5 pixel (or larger) window W within the active sensor array is 11071 chosen. The term 'pixel' here is taken to mean a group of 4 Bayer 11072 mosaic channels (R, Gr, Gb, B). The location and size of the window 11073 chosen is implementation defined, and should be chosen to provide a 11074 green split estimate that is both representative of the entire image 11075 for this camera sensor, and can be calculated quickly. 11076 1. The arithmetic mean of the green channels from the red 11077 rows (mean_Gr) within W is computed. 11078 1. The arithmetic mean of the green channels from the blue 11079 rows (mean_Gb) within W is computed. 11080 1. The maximum ratio R of the two means is computed as follows: 11081 `R = max((mean_Gr + 1)/(mean_Gb + 1), (mean_Gb + 1)/(mean_Gr + 1))` 11082 11083 The ratio R is the green split divergence reported for this property, 11084 which represents how much the green channels differ in the mosaic 11085 pattern. This value is typically used to determine the treatment of 11086 the green mosaic channels when demosaicing. 11087 11088 The green split value can be roughly interpreted as follows: 11089 11090 * R &lt; 1.03 is a negligible split (&lt;3% divergence). 11091 * 1.20 &lt;= R &gt;= 1.03 will require some software 11092 correction to avoid demosaic errors (3-20% divergence). 11093 * R &gt; 1.20 will require strong software correction to produce 11094 a usable image (&gt;20% divergence). 11095 11096 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 11097 the camera device has RAW capability. 11098 </details> 11099 <hal_details> 11100 The green split given may be a static value based on prior 11101 characterization of the camera sensor using the green split 11102 calculation method given here over a large, representative, sample 11103 set of images. Other methods of calculation that produce equivalent 11104 results, and can be interpreted in the same manner, may be used. 11105 </hal_details> 11106 <tag id="RAW" /> 11107 </entry> 11108 </dynamic> 11109 <controls> 11110 <entry name="testPatternData" type="int32" visibility="public" optional="true" container="array"> 11111 <array> 11112 <size>4</size> 11113 </array> 11114 <description> 11115 A pixel `[R, G_even, G_odd, B]` that supplies the test pattern 11116 when android.sensor.testPatternMode is SOLID_COLOR. 11117 </description> 11118 <details> 11119 Each color channel is treated as an unsigned 32-bit integer. 11120 The camera device then uses the most significant X bits 11121 that correspond to how many bits are in its Bayer raw sensor 11122 output. 11123 11124 For example, a sensor with RAW10 Bayer output would use the 11125 10 most significant bits from each color channel. 11126 </details> 11127 <hal_details> 11128 </hal_details> 11129 </entry> 11130 <entry name="testPatternMode" type="int32" visibility="public" optional="true" 11131 enum="true"> 11132 <enum> 11133 <value>OFF 11134 <notes>No test pattern mode is used, and the camera 11135 device returns captures from the image sensor. 11136 11137 This is the default if the key is not set.</notes> 11138 </value> 11139 <value>SOLID_COLOR 11140 <notes> 11141 Each pixel in `[R, G_even, G_odd, B]` is replaced by its 11142 respective color channel provided in 11143 android.sensor.testPatternData. 11144 11145 For example: 11146 11147 android.sensor.testPatternData = [0, 0xFFFFFFFF, 0xFFFFFFFF, 0] 11148 11149 All green pixels are 100% green. All red/blue pixels are black. 11150 11151 android.sensor.testPatternData = [0xFFFFFFFF, 0, 0xFFFFFFFF, 0] 11152 11153 All red pixels are 100% red. Only the odd green pixels 11154 are 100% green. All blue pixels are 100% black. 11155 </notes> 11156 </value> 11157 <value>COLOR_BARS 11158 <notes> 11159 All pixel data is replaced with an 8-bar color pattern. 11160 11161 The vertical bars (left-to-right) are as follows: 11162 11163 * 100% white 11164 * yellow 11165 * cyan 11166 * green 11167 * magenta 11168 * red 11169 * blue 11170 * black 11171 11172 In general the image would look like the following: 11173 11174 W Y C G M R B K 11175 W Y C G M R B K 11176 W Y C G M R B K 11177 W Y C G M R B K 11178 W Y C G M R B K 11179 . . . . . . . . 11180 . . . . . . . . 11181 . . . . . . . . 11182 11183 (B = Blue, K = Black) 11184 11185 Each bar should take up 1/8 of the sensor pixel array width. 11186 When this is not possible, the bar size should be rounded 11187 down to the nearest integer and the pattern can repeat 11188 on the right side. 11189 11190 Each bar's height must always take up the full sensor 11191 pixel array height. 11192 11193 Each pixel in this test pattern must be set to either 11194 0% intensity or 100% intensity. 11195 </notes> 11196 </value> 11197 <value>COLOR_BARS_FADE_TO_GRAY 11198 <notes> 11199 The test pattern is similar to COLOR_BARS, except that 11200 each bar should start at its specified color at the top, 11201 and fade to gray at the bottom. 11202 11203 Furthermore each bar is further subdivided into a left and 11204 right half. The left half should have a smooth gradient, 11205 and the right half should have a quantized gradient. 11206 11207 In particular, the right half's should consist of blocks of the 11208 same color for 1/16th active sensor pixel array width. 11209 11210 The least significant bits in the quantized gradient should 11211 be copied from the most significant bits of the smooth gradient. 11212 11213 The height of each bar should always be a multiple of 128. 11214 When this is not the case, the pattern should repeat at the bottom 11215 of the image. 11216 </notes> 11217 </value> 11218 <value>PN9 11219 <notes> 11220 All pixel data is replaced by a pseudo-random sequence 11221 generated from a PN9 512-bit sequence (typically implemented 11222 in hardware with a linear feedback shift register). 11223 11224 The generator should be reset at the beginning of each frame, 11225 and thus each subsequent raw frame with this test pattern should 11226 be exactly the same as the last. 11227 </notes> 11228 </value> 11229 <value visibility="test" hal_version="3.6">BLACK 11230 <notes> 11231 All pixel data is replaced by 0% intensity (black) values. 11232 11233 This test pattern is identical to SOLID_COLOR with a value of `[0, 0, 0, 0]` for 11234 android.sensor.testPatternData. It is recommended that devices implement full 11235 SOLID_COLOR support instead, but BLACK can be used to provide minimal support for a 11236 test pattern suitable for privacy use cases. 11237 </notes> 11238 </value> 11239 <value id="256">CUSTOM1 11240 <notes>The first custom test pattern. All custom patterns that are 11241 available only on this camera device are at least this numeric 11242 value. 11243 11244 All of the custom test patterns will be static 11245 (that is the raw image must not vary from frame to frame). 11246 </notes> 11247 </value> 11248 </enum> 11249 <description>When enabled, the sensor sends a test pattern instead of 11250 doing a real exposure from the camera. 11251 </description> 11252 <range>android.sensor.availableTestPatternModes</range> 11253 <details> 11254 When a test pattern is enabled, all manual sensor controls specified 11255 by android.sensor.* will be ignored. All other controls should 11256 work as normal. 11257 11258 For example, if manual flash is enabled, flash firing should still 11259 occur (and that the test pattern remain unmodified, since the flash 11260 would not actually affect it). 11261 11262 Defaults to OFF. 11263 </details> 11264 <hal_details> 11265 All test patterns are specified in the Bayer domain. 11266 11267 The HAL may choose to substitute test patterns from the sensor 11268 with test patterns from on-device memory. In that case, it should be 11269 indistinguishable to the ISP whether the data came from the 11270 sensor interconnect bus (such as CSI2) or memory. 11271 11272 For privacy use cases, if the camera device: 11273 11274 * supports SOLID_COLOR or BLACK test patterns, 11275 * is a logical multi-camera, and 11276 * lists testPatternMode as a physical request key, 11277 11278 Each physical camera must support the same SOLID_COLOR and/or BLACK test patterns 11279 as the logical camera. 11280 </hal_details> 11281 </entry> 11282 </controls> 11283 <dynamic> 11284 <clone entry="android.sensor.testPatternData" kind="controls"> 11285 </clone> 11286 <clone entry="android.sensor.testPatternMode" kind="controls"> 11287 </clone> 11288 </dynamic> 11289 <static> 11290 <entry name="availableTestPatternModes" type="int32" visibility="public" optional="true" 11291 type_notes="list of enums" container="array"> 11292 <array> 11293 <size>n</size> 11294 </array> 11295 <description>List of sensor test pattern modes for android.sensor.testPatternMode 11296 supported by this camera device. 11297 </description> 11298 <range>Any value listed in android.sensor.testPatternMode</range> 11299 <details> 11300 Defaults to OFF, and always includes OFF if defined. 11301 </details> 11302 <hal_details> 11303 All custom modes must be >= CUSTOM1. 11304 </hal_details> 11305 </entry> 11306 </static> 11307 <dynamic> 11308 <entry name="rollingShutterSkew" type="int64" visibility="public" hwlevel="limited"> 11309 <description>Duration between the start of exposure for the first row of the image sensor, 11310 and the start of exposure for one past the last row of the image sensor.</description> 11311 <units>Nanoseconds</units> 11312 <range> &gt;= 0 and &lt; 11313 {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration}.</range> 11314 <details> 11315 This is the exposure time skew between the first and `(last+1)` row exposure start times. The 11316 first row and the last row are the first and last rows inside of the 11317 android.sensor.info.activeArraySize. 11318 11319 For typical camera sensors that use rolling shutters, this is also equivalent to the frame 11320 readout time. 11321 11322 If the image sensor is operating in a binned or cropped mode due to the current output 11323 target resolutions, it's possible this skew is reported to be larger than the exposure 11324 time, for example, since it is based on the full array even if a partial array is read 11325 out. Be sure to scale the number to cover the section of the sensor actually being used 11326 for the outputs you care about. So if your output covers N rows of the active array of 11327 height H, scale this value by N/H to get the total skew for that viewport. 11328 11329 *Note:* Prior to Android 11, this field was described as measuring duration from 11330 first to last row of the image sensor, which is not equal to the frame readout time for a 11331 rolling shutter sensor. Implementations generally reported the latter value, so to resolve 11332 the inconsistency, the description has been updated to range from (first, last+1) row 11333 exposure start, instead. 11334 </details> 11335 <hal_details> 11336 The HAL must report `0` if the sensor is using global shutter, where all pixels begin 11337 exposure at the same time. 11338 </hal_details> 11339 <tag id="V1" /> 11340 </entry> 11341 </dynamic> 11342 <static> 11343 <entry name="opticalBlackRegions" type="int32" visibility="public" optional="true" 11344 container="array" typedef="rectangle"> 11345 <array> 11346 <size>4</size> 11347 <size>num_regions</size> 11348 </array> 11349 <description>List of disjoint rectangles indicating the sensor 11350 optically shielded black pixel regions. 11351 </description> 11352 <details> 11353 In most camera sensors, the active array is surrounded by some 11354 optically shielded pixel areas. By blocking light, these pixels 11355 provides a reliable black reference for black level compensation 11356 in active array region. 11357 11358 This key provides a list of disjoint rectangles specifying the 11359 regions of optically shielded (with metal shield) black pixel 11360 regions if the camera device is capable of reading out these black 11361 pixels in the output raw images. In comparison to the fixed black 11362 level values reported by android.sensor.blackLevelPattern, this key 11363 may provide a more accurate way for the application to calculate 11364 black level of each captured raw images. 11365 11366 When this key is reported, the android.sensor.dynamicBlackLevel and 11367 android.sensor.dynamicWhiteLevel will also be reported. 11368 </details> 11369 <ndk_details> 11370 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 11371 </ndk_details> 11372 <hal_details> 11373 This array contains (xmin, ymin, width, height). The (xmin, ymin) 11374 must be &gt;= (0,0) and &lt;= 11375 android.sensor.info.pixelArraySize. The (width, height) must be 11376 &lt;= android.sensor.info.pixelArraySize. Each region must be 11377 outside the region reported by 11378 android.sensor.info.preCorrectionActiveArraySize. 11379 11380 The HAL must report minimal number of disjoint regions for the 11381 optically shielded back pixel regions. For example, if a region can 11382 be covered by one rectangle, the HAL must not split this region into 11383 multiple rectangles. 11384 </hal_details> 11385 </entry> 11386 </static> 11387 <dynamic> 11388 <entry name="dynamicBlackLevel" type="float" visibility="public" 11389 optional="true" type_notes="2x2 raw count block" container="array"> 11390 <array> 11391 <size>4</size> 11392 </array> 11393 <description> 11394 A per-frame dynamic black level offset for each of the color filter 11395 arrangement (CFA) mosaic channels. 11396 </description> 11397 <range>&gt;= 0 for each.</range> 11398 <details> 11399 Camera sensor black levels may vary dramatically for different 11400 capture settings (e.g. android.sensor.sensitivity). The fixed black 11401 level reported by android.sensor.blackLevelPattern may be too 11402 inaccurate to represent the actual value on a per-frame basis. The 11403 camera device internal pipeline relies on reliable black level values 11404 to process the raw images appropriately. To get the best image 11405 quality, the camera device may choose to estimate the per frame black 11406 level values either based on optically shielded black regions 11407 (android.sensor.opticalBlackRegions) or its internal model. 11408 11409 This key reports the camera device estimated per-frame zero light 11410 value for each of the CFA mosaic channels in the camera sensor. The 11411 android.sensor.blackLevelPattern may only represent a coarse 11412 approximation of the actual black level values. This value is the 11413 black level used in camera device internal image processing pipeline 11414 and generally more accurate than the fixed black level values. 11415 However, since they are estimated values by the camera device, they 11416 may not be as accurate as the black level values calculated from the 11417 optical black pixels reported by android.sensor.opticalBlackRegions. 11418 11419 The values are given in the same order as channels listed for the CFA 11420 layout key (see android.sensor.info.colorFilterArrangement), i.e. the 11421 nth value given corresponds to the black level offset for the nth 11422 color channel listed in the CFA. 11423 11424 For a MONOCHROME camera, all of the 2x2 channels must have the same values. 11425 11426 This key will be available if android.sensor.opticalBlackRegions is available or the 11427 camera device advertises this key via {@link 11428 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 11429 </details> 11430 <hal_details> 11431 The values are given in row-column scan order, with the first value 11432 corresponding to the element of the CFA in row=0, column=0. 11433 </hal_details> 11434 <tag id="RAW" /> 11435 </entry> 11436 <entry name="dynamicWhiteLevel" type="int32" visibility="public" 11437 optional="true" > 11438 <description> 11439 Maximum raw value output by sensor for this frame. 11440 </description> 11441 <range> &gt;= 0</range> 11442 <details> 11443 Since the android.sensor.blackLevelPattern may change for different 11444 capture settings (e.g., android.sensor.sensitivity), the white 11445 level will change accordingly. This key is similar to 11446 android.sensor.info.whiteLevel, but specifies the camera device 11447 estimated white level for each frame. 11448 11449 This key will be available if android.sensor.opticalBlackRegions is 11450 available or the camera device advertises this key via 11451 {@link android.hardware.camera2.CameraCharacteristics#getAvailableCaptureRequestKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 11452 </details> 11453 <hal_details> 11454 The full bit depth of the sensor must be available in the raw data, 11455 so the value for linear sensors should not be significantly lower 11456 than maximum raw value supported, i.e. 2^(sensor bits per pixel). 11457 </hal_details> 11458 <tag id="RAW" /> 11459 </entry> 11460 </dynamic> 11461 <static> 11462 <entry name="opaqueRawSize" type="int32" visibility="system" container="array"> 11463 <array> 11464 <size>n</size> 11465 <size>3</size> 11466 </array> 11467 <description>Size in bytes for all the listed opaque RAW buffer sizes</description> 11468 <range>Must be large enough to fit the opaque RAW of corresponding size produced by 11469 the camera</range> 11470 <details> 11471 This configurations are listed as `(width, height, size_in_bytes)` tuples. 11472 This is used for sizing the gralloc buffers for opaque RAW buffers. 11473 All RAW_OPAQUE output stream configuration listed in 11474 android.scaler.availableStreamConfigurations will have a corresponding tuple in 11475 this key. 11476 </details> 11477 <hal_details> 11478 This key is added in legacy HAL3.4. 11479 11480 For legacy HAL3.4 or above: devices advertising RAW_OPAQUE format output must list this 11481 key. For legacy HAL3.3 or earlier devices: if RAW_OPAQUE ouput is advertised, camera 11482 framework will derive this key by assuming each pixel takes two bytes and no padding bytes 11483 between rows. 11484 </hal_details> 11485 </entry> 11486 <entry name="opaqueRawSizeMaximumResolution" type="int32" visibility="system" 11487 container="array" hal_version="3.6"> 11488 <array> 11489 <size>n</size> 11490 <size>3</size> 11491 </array> 11492 <description>Size in bytes for all the listed opaque RAW buffer sizes when 11493 android.sensor.pixelMode is set to 11494 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 11495 </description> 11496 <range>Must be large enough to fit the opaque RAW of corresponding size produced by 11497 the camera</range> 11498 <details> 11499 Refer to android.sensor.opaqueRawSize for details. 11500 </details> 11501 <hal_details> 11502 Refer to android.sensor.opaqueRawSize for details. 11503 </hal_details> 11504 </entry> 11505 </static> 11506 <controls> 11507 <entry name="pixelMode" type="byte" visibility="public" enum="true" 11508 hal_version="3.6"> 11509 <enum> 11510 <value>DEFAULT 11511 <notes> This is the default sensor pixel mode. 11512 </notes> 11513 </value> 11514 <value>MAXIMUM_RESOLUTION 11515 <notes> 11516 In this mode, sensors typically do not bin pixels, as a result can offer larger 11517 image sizes. 11518 </notes> 11519 </value> 11520 </enum> 11521 <description> 11522 Switches sensor pixel mode between maximum resolution mode and default mode. 11523 </description> 11524 <details> 11525 This key controls whether the camera sensor operates in 11526 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 11527 mode or not. By default, all camera devices operate in 11528 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_DEFAULT} mode. 11529 When operating in 11530 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_DEFAULT} mode, sensors 11531 would typically perform pixel binning in order to improve low light 11532 performance, noise reduction etc. However, in 11533 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 11534 mode, sensors typically operate in unbinned mode allowing for a larger image size. 11535 The stream configurations supported in 11536 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 11537 mode are also different from those of 11538 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_DEFAULT} mode. 11539 They can be queried through 11540 {@link android.hardware.camera2.CameraCharacteristics#get} with 11541 {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP_MAXIMUM_RESOLUTION}. 11542 Unless reported by both 11543 {@link android.hardware.camera2.params.StreamConfigurationMap}s, the outputs from 11544 `android.scaler.streamConfigurationMapMaximumResolution` and 11545 `android.scaler.streamConfigurationMap` 11546 must not be mixed in the same CaptureRequest. In other words, these outputs are 11547 exclusive to each other. 11548 This key does not need to be set for reprocess requests. 11549 This key will be be present on devices supporting the 11550 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 11551 capability. It may also be present on devices which do not support the aforementioned 11552 capability. In that case: 11553 11554 * The mandatory stream combinations listed in 11555 android.scaler.mandatoryMaximumResolutionStreamCombinations 11556 would not apply. 11557 11558 * The bayer pattern of {@code RAW} streams when 11559 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 11560 is selected will be the one listed in android.sensor.info.binningFactor. 11561 11562 * The following keys will always be present: 11563 11564 * android.scaler.streamConfigurationMapMaximumResolution 11565 * android.sensor.info.activeArraySizeMaximumResolution 11566 * android.sensor.info.pixelArraySizeMaximumResolution 11567 * android.sensor.info.preCorrectionActiveArraySizeMaximumResolution 11568 </details> 11569 </entry> 11570 </controls> 11571 <dynamic> 11572 <clone entry="android.sensor.pixelMode" kind="controls"> 11573 </clone> 11574 <entry name="rawBinningFactorUsed" type="byte" visibility="public" enum="true" 11575 typedef="boolean" hal_version="3.6"> 11576 <enum> 11577 <value>TRUE 11578 <notes> The `RAW` targets in this capture have android.sensor.info.binningFactor as the 11579 bayer pattern. 11580 </notes> 11581 </value> 11582 <value>FALSE 11583 <notes> The `RAW` targets have a regular bayer pattern in this capture. 11584 </notes> 11585 </value> 11586 </enum> 11587 <description> 11588 Whether `RAW` images requested have their bayer pattern as described by 11589 android.sensor.info.binningFactor. 11590 </description> 11591 <details> 11592 This key will only be present in devices advertising the 11593 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 11594 capability which also advertise `REMOSAIC_REPROCESSING` capability. On all other devices 11595 RAW targets will have a regular bayer pattern. 11596 </details> 11597 </entry> 11598 </dynamic> 11599 <static> 11600 <entry name="readoutTimestamp" type="byte" visibility="java_public" 11601 enum="true" hwlevel="legacy" hal_version="3.8"> 11602 <enum> 11603 <value>NOT_SUPPORTED 11604 <notes>This camera device doesn't support readout timestamp and onReadoutStarted 11605 callback. 11606 </notes> 11607 </value> 11608 <value>HARDWARE 11609 <notes>This camera device supports the onReadoutStarted callback as well as outputting 11610 readout timestamps. The readout timestamp is generated by the camera hardware and it 11611 has the same accuracy and timing characteristics of the start-of-exposure time. 11612 </notes> 11613 </value> 11614 </enum> 11615 <description>Whether or not the camera device supports readout timestamp and 11616 {@code onReadoutStarted} callback.</description> 11617 <details> 11618 If this tag is {@code HARDWARE}, the camera device calls 11619 {@link CameraCaptureSession.CaptureCallback#onReadoutStarted} in addition to the 11620 {@link CameraCaptureSession.CaptureCallback#onCaptureStarted} callback for each capture. 11621 The timestamp passed into the callback is the start of camera image readout rather than 11622 the start of the exposure. The timestamp source of 11623 {@link CameraCaptureSession.CaptureCallback#onReadoutStarted} is the same as that of 11624 {@link CameraCaptureSession.CaptureCallback#onCaptureStarted}. 11625 11626 In addition, the application can switch an output surface's timestamp from start of 11627 exposure to start of readout by calling 11628 {@link android.hardware.camera2.params.OutputConfiguration#setReadoutTimestampEnabled}. 11629 11630 The readout timestamp is beneficial for video recording, because the encoder favors 11631 uniform timestamps, and the readout timestamps better reflect the cadence camera sensors 11632 output data. 11633 11634 Note that the camera device produces the start-of-exposure and start-of-readout callbacks 11635 together. As a result, the {@link CameraCaptureSession.CaptureCallback#onReadoutStarted} 11636 is called right after {@link CameraCaptureSession.CaptureCallback#onCaptureStarted}. The 11637 difference in start-of-readout and start-of-exposure is the sensor exposure time, plus 11638 certain constant offset. The offset is usually due to camera sensor level crop, and it is 11639 generally constant over time for the same set of output resolutions and capture settings. 11640 </details> 11641 <hal_details> 11642 This property may be set by HAL layers that implement the AIDL interface. If not set 11643 camera framework will implicitly set it to HARDWARE for all AIDL HALs. Camera framework 11644 will force set this to NOT_SUPPORTED for all HIDL HALs, regerdless of whether the HAL 11645 provided a value or not. 11646 </hal_details> 11647 </entry> 11648 </static> 11649 </section> 11650 <section name="shading"> 11651 <controls> 11652 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 11653 <enum> 11654 <value>OFF 11655 <notes>No lens shading correction is applied.</notes></value> 11656 <value>FAST 11657 <notes>Apply lens shading corrections, without slowing 11658 frame rate relative to sensor raw output</notes></value> 11659 <value>HIGH_QUALITY 11660 <notes>Apply high-quality lens shading correction, at the 11661 cost of possibly reduced frame rate.</notes></value> 11662 </enum> 11663 <description>Quality of lens shading correction applied 11664 to the image data.</description> 11665 <range>android.shading.availableModes</range> 11666 <details> 11667 When set to OFF mode, no lens shading correction will be applied by the 11668 camera device, and an identity lens shading map data will be provided 11669 if `android.statistics.lensShadingMapMode == ON`. For example, for lens 11670 shading map with size of `[ 4, 3 ]`, 11671 the output android.statistics.lensShadingCorrectionMap for this case will be an identity 11672 map shown below: 11673 11674 [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11675 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11676 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11677 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11678 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11679 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] 11680 11681 When set to other modes, lens shading correction will be applied by the camera 11682 device. Applications can request lens shading map data by setting 11683 android.statistics.lensShadingMapMode to ON, and then the camera device will provide lens 11684 shading map data in android.statistics.lensShadingCorrectionMap; the returned shading map 11685 data will be the one applied by the camera device for this capture request. 11686 11687 The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore 11688 the reliability of the map data may be affected by the AE and AWB algorithms. When AE and 11689 AWB are in AUTO modes(android.control.aeMode `!=` OFF and android.control.awbMode `!=` 11690 OFF), to get best results, it is recommended that the applications wait for the AE and AWB 11691 to be converged before using the returned shading map data. 11692 </details> 11693 </entry> 11694 <entry name="strength" type="byte"> 11695 <description>Control the amount of shading correction 11696 applied to the images</description> 11697 <units>unitless: 1-10; 10 is full shading 11698 compensation</units> 11699 <tag id="FUTURE" /> 11700 </entry> 11701 </controls> 11702 <dynamic> 11703 <clone entry="android.shading.mode" kind="controls"> 11704 </clone> 11705 </dynamic> 11706 <static> 11707 <entry name="availableModes" type="byte" visibility="public" 11708 type_notes="List of enums (android.shading.mode)." container="array" 11709 typedef="enumList" hwlevel="legacy"> 11710 <array> 11711 <size>n</size> 11712 </array> 11713 <description> 11714 List of lens shading modes for android.shading.mode that are supported by this camera device. 11715 </description> 11716 <range>Any value listed in android.shading.mode</range> 11717 <details> 11718 This list contains lens shading modes that can be set for the camera device. 11719 Camera devices that support the MANUAL_POST_PROCESSING capability will always 11720 list OFF and FAST mode. This includes all FULL level devices. 11721 LEGACY devices will always only support FAST mode. 11722 </details> 11723 <hal_details> 11724 HAL must support both FAST and HIGH_QUALITY if lens shading correction control is 11725 available on the camera device, but the underlying implementation can be the same for 11726 both modes. That is, if the highest quality implementation on the camera device does not 11727 slow down capture rate, then FAST and HIGH_QUALITY will generate the same output. 11728 </hal_details> 11729 </entry> 11730 </static> 11731 </section> 11732 <section name="statistics"> 11733 <controls> 11734 <entry name="faceDetectMode" type="byte" visibility="public" enum="true" 11735 hwlevel="legacy"> 11736 <enum> 11737 <value>OFF 11738 <notes>Do not include face detection statistics in capture 11739 results.</notes></value> 11740 <value optional="true">SIMPLE 11741 <notes>Return face rectangle and confidence values only. 11742 </notes></value> 11743 <value optional="true">FULL 11744 <notes>Return all face 11745 metadata. 11746 11747 In this mode, face rectangles, scores, landmarks, and face IDs are all valid. 11748 </notes></value> 11749 </enum> 11750 <description>Operating mode for the face detector 11751 unit.</description> 11752 <range>android.statistics.info.availableFaceDetectModes</range> 11753 <details>Whether face detection is enabled, and whether it 11754 should output just the basic fields or the full set of 11755 fields.</details> 11756 <hal_details> 11757 SIMPLE mode must fill in android.statistics.faceRectangles and 11758 android.statistics.faceScores. 11759 FULL mode must also fill in android.statistics.faceIds, and 11760 android.statistics.faceLandmarks. 11761 </hal_details> 11762 <tag id="BC" /> 11763 </entry> 11764 <entry name="histogramMode" type="byte" enum="true" typedef="boolean"> 11765 <enum> 11766 <value>OFF</value> 11767 <value>ON</value> 11768 </enum> 11769 <description>Operating mode for histogram 11770 generation</description> 11771 <tag id="FUTURE" /> 11772 </entry> 11773 <entry name="sharpnessMapMode" type="byte" enum="true" typedef="boolean"> 11774 <enum> 11775 <value>OFF</value> 11776 <value>ON</value> 11777 </enum> 11778 <description>Operating mode for sharpness map 11779 generation</description> 11780 <tag id="FUTURE" /> 11781 </entry> 11782 <entry name="hotPixelMapMode" type="byte" visibility="public" enum="true" 11783 typedef="boolean"> 11784 <enum> 11785 <value>OFF 11786 <notes>Hot pixel map production is disabled. 11787 </notes></value> 11788 <value>ON 11789 <notes>Hot pixel map production is enabled. 11790 </notes></value> 11791 </enum> 11792 <description> 11793 Operating mode for hot pixel map generation. 11794 </description> 11795 <range>android.statistics.info.availableHotPixelMapModes</range> 11796 <details> 11797 If set to `true`, a hot pixel map is returned in android.statistics.hotPixelMap. 11798 If set to `false`, no hot pixel map will be returned. 11799 </details> 11800 <tag id="V1" /> 11801 <tag id="RAW" /> 11802 </entry> 11803 </controls> 11804 <static> 11805 <namespace name="info"> 11806 <entry name="availableFaceDetectModes" type="byte" 11807 visibility="public" 11808 type_notes="List of enums from android.statistics.faceDetectMode" 11809 container="array" 11810 typedef="enumList" 11811 hwlevel="legacy"> 11812 <array> 11813 <size>n</size> 11814 </array> 11815 <description>List of face detection modes for android.statistics.faceDetectMode that are 11816 supported by this camera device. 11817 </description> 11818 <range>Any value listed in android.statistics.faceDetectMode</range> 11819 <details>OFF is always supported. 11820 </details> 11821 </entry> 11822 <entry name="histogramBucketCount" type="int32"> 11823 <description>Number of histogram buckets 11824 supported</description> 11825 <range>&gt;= 64</range> 11826 <tag id="FUTURE" /> 11827 </entry> 11828 <entry name="maxFaceCount" type="int32" visibility="public" hwlevel="legacy"> 11829 <description>The maximum number of simultaneously detectable 11830 faces.</description> 11831 <range>0 for cameras without available face detection; otherwise: 11832 `>=4` for LIMITED or FULL hwlevel devices or 11833 `>0` for LEGACY devices.</range> 11834 <tag id="BC" /> 11835 </entry> 11836 <entry name="maxHistogramCount" type="int32"> 11837 <description>Maximum value possible for a histogram 11838 bucket</description> 11839 <tag id="FUTURE" /> 11840 </entry> 11841 <entry name="maxSharpnessMapValue" type="int32"> 11842 <description>Maximum value possible for a sharpness map 11843 region.</description> 11844 <tag id="FUTURE" /> 11845 </entry> 11846 <entry name="sharpnessMapSize" type="int32" 11847 type_notes="width x height" container="array" typedef="size"> 11848 <array> 11849 <size>2</size> 11850 </array> 11851 <description>Dimensions of the sharpness 11852 map</description> 11853 <range>Must be at least 32 x 32</range> 11854 <tag id="FUTURE" /> 11855 </entry> 11856 <entry name="availableHotPixelMapModes" type="byte" visibility="public" 11857 type_notes="list of enums" container="array" typedef="boolean"> 11858 <array> 11859 <size>n</size> 11860 </array> 11861 <description> 11862 List of hot pixel map output modes for android.statistics.hotPixelMapMode that are 11863 supported by this camera device. 11864 </description> 11865 <range>Any value listed in android.statistics.hotPixelMapMode</range> 11866 <details> 11867 If no hotpixel map output is available for this camera device, this will contain only 11868 `false`. 11869 11870 ON is always supported on devices with the RAW capability. 11871 </details> 11872 <tag id="V1" /> 11873 <tag id="RAW" /> 11874 </entry> 11875 <entry name="availableLensShadingMapModes" type="byte" visibility="public" 11876 type_notes="list of enums" container="array" typedef="enumList"> 11877 <array> 11878 <size>n</size> 11879 </array> 11880 <description> 11881 List of lens shading map output modes for android.statistics.lensShadingMapMode that 11882 are supported by this camera device. 11883 </description> 11884 <range>Any value listed in android.statistics.lensShadingMapMode</range> 11885 <details> 11886 If no lens shading map output is available for this camera device, this key will 11887 contain only OFF. 11888 11889 ON is always supported on devices with the RAW capability. 11890 LEGACY mode devices will always only support OFF. 11891 </details> 11892 </entry> 11893 <entry name="availableOisDataModes" type="byte" visibility="public" 11894 type_notes="list of enums" container="array" typedef="enumList" hal_version="3.3"> 11895 <array> 11896 <size>n</size> 11897 </array> 11898 <description> 11899 List of OIS data output modes for android.statistics.oisDataMode that 11900 are supported by this camera device. 11901 </description> 11902 <range>Any value listed in android.statistics.oisDataMode</range> 11903 <details> 11904 If no OIS data output is available for this camera device, this key will 11905 contain only OFF. 11906 </details> 11907 </entry> 11908 </namespace> 11909 </static> 11910 <dynamic> 11911 <clone entry="android.statistics.faceDetectMode" 11912 kind="controls"></clone> 11913 <entry name="faceIds" type="int32" visibility="ndk_public" 11914 container="array" hwlevel="legacy"> 11915 <array> 11916 <size>n</size> 11917 </array> 11918 <description>List of unique IDs for detected faces.</description> 11919 <details> 11920 Each detected face is given a unique ID that is valid for as long as the face is visible 11921 to the camera device. A face that leaves the field of view and later returns may be 11922 assigned a new ID. 11923 11924 Only available if android.statistics.faceDetectMode == FULL</details> 11925 <tag id="BC" /> 11926 </entry> 11927 <entry name="faceLandmarks" type="int32" visibility="ndk_public" 11928 type_notes="(leftEyeX, leftEyeY, rightEyeX, rightEyeY, mouthX, mouthY)" 11929 container="array" hwlevel="legacy"> 11930 <array> 11931 <size>n</size> 11932 <size>6</size> 11933 </array> 11934 <description>List of landmarks for detected 11935 faces.</description> 11936 <details> 11937 For devices not supporting android.distortionCorrection.mode control, the coordinate 11938 system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being 11939 the top-left pixel of the active array. 11940 11941 For devices supporting android.distortionCorrection.mode control, the coordinate 11942 system depends on the mode being set. 11943 When the distortion correction mode is OFF, the coordinate system follows 11944 android.sensor.info.preCorrectionActiveArraySize, with 11945 `(0, 0)` being the top-left pixel of the pre-correction active array. 11946 When the distortion correction mode is not OFF, the coordinate system follows 11947 android.sensor.info.activeArraySize, with 11948 `(0, 0)` being the top-left pixel of the active array. 11949 11950 Only available if android.statistics.faceDetectMode == FULL. 11951 11952 Starting from API level 30, the coordinate system of activeArraySize or 11953 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 11954 pre-zoomRatio field of view. This means that if the relative position of faces and 11955 the camera device doesn't change, when zooming in by increasing 11956 android.control.zoomRatio, the face landmarks move farther away from the center of the 11957 activeArray or preCorrectionActiveArray. If android.control.zoomRatio is set to 1.0 11958 (default), the face landmarks coordinates won't change as android.scaler.cropRegion 11959 changes. See android.control.zoomRatio for details. Whether to use activeArraySize or 11960 preCorrectionActiveArraySize still depends on distortion correction mode. 11961 </details> 11962 <hal_details> 11963 HAL must always report face landmarks in the coordinate system of pre-correction 11964 active array. 11965 </hal_details> 11966 <tag id="BC" /> 11967 </entry> 11968 <entry name="faceRectangles" type="int32" visibility="ndk_public" 11969 type_notes="(xmin, ymin, xmax, ymax). (0,0) is top-left of active pixel area" 11970 container="array" typedef="rectangle" hwlevel="legacy"> 11971 <array> 11972 <size>n</size> 11973 <size>4</size> 11974 </array> 11975 <description>List of the bounding rectangles for detected 11976 faces.</description> 11977 <details> 11978 For devices not supporting android.distortionCorrection.mode control, the coordinate 11979 system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being 11980 the top-left pixel of the active array. 11981 11982 For devices supporting android.distortionCorrection.mode control, the coordinate 11983 system depends on the mode being set. 11984 When the distortion correction mode is OFF, the coordinate system follows 11985 android.sensor.info.preCorrectionActiveArraySize, with 11986 `(0, 0)` being the top-left pixel of the pre-correction active array. 11987 When the distortion correction mode is not OFF, the coordinate system follows 11988 android.sensor.info.activeArraySize, with 11989 `(0, 0)` being the top-left pixel of the active array. 11990 11991 Only available if android.statistics.faceDetectMode != OFF. 11992 11993 Starting from API level 30, the coordinate system of activeArraySize or 11994 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 11995 pre-zoomRatio field of view. This means that if the relative position of faces and 11996 the camera device doesn't change, when zooming in by increasing 11997 android.control.zoomRatio, the face rectangles grow larger and move farther away from 11998 the center of the activeArray or preCorrectionActiveArray. If android.control.zoomRatio 11999 is set to 1.0 (default), the face rectangles won't change as android.scaler.cropRegion 12000 changes. See android.control.zoomRatio for details. Whether to use activeArraySize or 12001 preCorrectionActiveArraySize still depends on distortion correction mode. 12002 </details> 12003 <ndk_details> 12004 The data representation is `int[4]`, which maps to `(left, top, right, bottom)`. 12005 </ndk_details> 12006 <hal_details> 12007 HAL must always report face rectangles in the coordinate system of pre-correction 12008 active array. 12009 </hal_details> 12010 <tag id="BC" /> 12011 </entry> 12012 <entry name="faceScores" type="byte" visibility="ndk_public" 12013 container="array" hwlevel="legacy"> 12014 <array> 12015 <size>n</size> 12016 </array> 12017 <description>List of the face confidence scores for 12018 detected faces</description> 12019 <range>1-100</range> 12020 <details>Only available if android.statistics.faceDetectMode != OFF. 12021 </details> 12022 <hal_details> 12023 The value should be meaningful (for example, setting 100 at 12024 all times is illegal).</hal_details> 12025 <tag id="BC" /> 12026 </entry> 12027 <entry name="faces" type="int32" visibility="java_public" synthetic="true" 12028 container="array" typedef="face" hwlevel="legacy"> 12029 <array> 12030 <size>n</size> 12031 </array> 12032 <description>List of the faces detected through camera face detection 12033 in this capture.</description> 12034 <details> 12035 Only available if android.statistics.faceDetectMode `!=` OFF. 12036 </details> 12037 </entry> 12038 <entry name="histogram" type="int32" 12039 type_notes="count of pixels for each color channel that fall into each histogram bucket, scaled to be between 0 and maxHistogramCount" 12040 container="array"> 12041 <array> 12042 <size>n</size> 12043 <size>3</size> 12044 </array> 12045 <description>A 3-channel histogram based on the raw 12046 sensor data</description> 12047 <details>The k'th bucket (0-based) covers the input range 12048 (with w = android.sensor.info.whiteLevel) of [ k * w/N, 12049 (k + 1) * w / N ). If only a monochrome sharpness map is 12050 supported, all channels should have the same data</details> 12051 <tag id="FUTURE" /> 12052 </entry> 12053 <clone entry="android.statistics.histogramMode" 12054 kind="controls"></clone> 12055 <entry name="sharpnessMap" type="int32" 12056 type_notes="estimated sharpness for each region of the input image. Normalized to be between 0 and maxSharpnessMapValue. Higher values mean sharper (better focused)" 12057 container="array"> 12058 <array> 12059 <size>n</size> 12060 <size>m</size> 12061 <size>3</size> 12062 </array> 12063 <description>A 3-channel sharpness map, based on the raw 12064 sensor data</description> 12065 <details>If only a monochrome sharpness map is supported, 12066 all channels should have the same data</details> 12067 <tag id="FUTURE" /> 12068 </entry> 12069 <clone entry="android.statistics.sharpnessMapMode" 12070 kind="controls"></clone> 12071 <entry name="lensShadingCorrectionMap" type="byte" visibility="java_public" 12072 typedef="lensShadingMap" hwlevel="full"> 12073 <description>The shading map is a low-resolution floating-point map 12074 that lists the coefficients used to correct for vignetting, for each 12075 Bayer color channel.</description> 12076 <range>Each gain factor is &gt;= 1</range> 12077 <details> 12078 The map provided here is the same map that is used by the camera device to 12079 correct both color shading and vignetting for output non-RAW images. 12080 12081 When there is no lens shading correction applied to RAW 12082 output images (android.sensor.info.lensShadingApplied `==` 12083 false), this map is the complete lens shading correction 12084 map; when there is some lens shading correction applied to 12085 the RAW output image (android.sensor.info.lensShadingApplied 12086 `==` true), this map reports the remaining lens shading 12087 correction map that needs to be applied to get shading 12088 corrected images that match the camera device's output for 12089 non-RAW formats. 12090 12091 Therefore, whatever the value of lensShadingApplied is, the lens 12092 shading map should always be applied to RAW images if the goal is to 12093 match the shading appearance of processed (non-RAW) images. 12094 12095 For a complete shading correction map, the least shaded 12096 section of the image will have a gain factor of 1; all 12097 other sections will have gains above 1. 12098 12099 When android.colorCorrection.mode = TRANSFORM_MATRIX, the map 12100 will take into account the colorCorrection settings. 12101 12102 The shading map is for the entire active pixel array, and is not 12103 affected by the crop region specified in the request. Each shading map 12104 entry is the value of the shading compensation map over a specific 12105 pixel on the sensor. Specifically, with a (N x M) resolution shading 12106 map, and an active pixel array size (W x H), shading map entry 12107 (x,y) ϵ (0 ... N-1, 0 ... M-1) is the value of the shading map at 12108 pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels. 12109 The map is assumed to be bilinearly interpolated between the sample points. 12110 12111 The channel order is [R, Geven, Godd, B], where Geven is the green 12112 channel for the even rows of a Bayer pattern, and Godd is the odd rows. 12113 The shading map is stored in a fully interleaved format. 12114 12115 The shading map will generally have on the order of 30-40 rows and columns, 12116 and will be smaller than 64x64. 12117 12118 As an example, given a very small map defined as: 12119 12120 width,height = [ 4, 3 ] 12121 values = 12122 [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2, 12123 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3, 12124 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0, 12125 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2, 12126 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2, 12127 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ] 12128 12129 The low-resolution scaling map images for each channel are 12130 (displayed using nearest-neighbor interpolation): 12131 12132  12133  12134  12135  12136 12137 As a visualization only, inverting the full-color map to recover an 12138 image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives: 12139 12140  12141 12142 For a MONOCHROME camera, all of the 2x2 channels must have the same values. An example 12143 shading map for such a camera is defined as: 12144 12145 android.lens.info.shadingMapSize = [ 4, 3 ] 12146 android.statistics.lensShadingMap = 12147 [ 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 12148 1.1, 1.1, 1.1, 1.1, 1.3, 1.3, 1.3, 1.3, 12149 1.2, 1.2, 1.2, 1.2, 1.1, 1.1, 1.1, 1.1, 12150 1.0, 1.0, 1.0, 1.0, 1.2, 1.2, 1.2, 1.2, 12151 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 12152 1.2, 1.2, 1.2, 1.2, 1.3, 1.3, 1.3, 1.3 ] 12153 12154 </details> 12155 </entry> 12156 <entry name="lensShadingMap" type="float" visibility="ndk_public" 12157 type_notes="2D array of float gain factors per channel to correct lens shading" 12158 container="array" hwlevel="full"> 12159 <array> 12160 <size>4</size> 12161 <size>n</size> 12162 <size>m</size> 12163 </array> 12164 <description>The shading map is a low-resolution floating-point map 12165 that lists the coefficients used to correct for vignetting and color shading, 12166 for each Bayer color channel of RAW image data.</description> 12167 <range>Each gain factor is &gt;= 1</range> 12168 <details> 12169 The map provided here is the same map that is used by the camera device to 12170 correct both color shading and vignetting for output non-RAW images. 12171 12172 When there is no lens shading correction applied to RAW 12173 output images (android.sensor.info.lensShadingApplied `==` 12174 false), this map is the complete lens shading correction 12175 map; when there is some lens shading correction applied to 12176 the RAW output image (android.sensor.info.lensShadingApplied 12177 `==` true), this map reports the remaining lens shading 12178 correction map that needs to be applied to get shading 12179 corrected images that match the camera device's output for 12180 non-RAW formats. 12181 12182 For a complete shading correction map, the least shaded 12183 section of the image will have a gain factor of 1; all 12184 other sections will have gains above 1. 12185 12186 When android.colorCorrection.mode = TRANSFORM_MATRIX, the map 12187 will take into account the colorCorrection settings. 12188 12189 The shading map is for the entire active pixel array, and is not 12190 affected by the crop region specified in the request. Each shading map 12191 entry is the value of the shading compensation map over a specific 12192 pixel on the sensor. Specifically, with a (N x M) resolution shading 12193 map, and an active pixel array size (W x H), shading map entry 12194 (x,y) ϵ (0 ... N-1, 0 ... M-1) is the value of the shading map at 12195 pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels. 12196 The map is assumed to be bilinearly interpolated between the sample points. 12197 12198 For a Bayer camera, the channel order is [R, Geven, Godd, B], where Geven is 12199 the green channel for the even rows of a Bayer pattern, and Godd is the odd rows. 12200 The shading map is stored in a fully interleaved format, and its size 12201 is provided in the camera static metadata by android.lens.info.shadingMapSize. 12202 12203 The shading map will generally have on the order of 30-40 rows and columns, 12204 and will be smaller than 64x64. 12205 12206 As an example, given a very small map for a Bayer camera defined as: 12207 12208 android.lens.info.shadingMapSize = [ 4, 3 ] 12209 android.statistics.lensShadingMap = 12210 [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2, 12211 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3, 12212 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0, 12213 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2, 12214 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2, 12215 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ] 12216 12217 The low-resolution scaling map images for each channel are 12218 (displayed using nearest-neighbor interpolation): 12219 12220  12221  12222  12223  12224 12225 As a visualization only, inverting the full-color map to recover an 12226 image of a gray wall (using bicubic interpolation for visual quality) 12227 as captured by the sensor gives: 12228 12229  12230 12231 For a MONOCHROME camera, all of the 2x2 channels must have the same values. An example 12232 shading map for such a camera is defined as: 12233 12234 android.lens.info.shadingMapSize = [ 4, 3 ] 12235 android.statistics.lensShadingMap = 12236 [ 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 12237 1.1, 1.1, 1.1, 1.1, 1.3, 1.3, 1.3, 1.3, 12238 1.2, 1.2, 1.2, 1.2, 1.1, 1.1, 1.1, 1.1, 12239 1.0, 1.0, 1.0, 1.0, 1.2, 1.2, 1.2, 1.2, 12240 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 12241 1.2, 1.2, 1.2, 1.2, 1.3, 1.3, 1.3, 1.3 ] 12242 12243 Note that the RAW image data might be subject to lens shading 12244 correction not reported on this map. Query 12245 android.sensor.info.lensShadingApplied to see if RAW image data has subject 12246 to lens shading correction. If android.sensor.info.lensShadingApplied 12247 is TRUE, the RAW image data is subject to partial or full lens shading 12248 correction. In the case full lens shading correction is applied to RAW 12249 images, the gain factor map reported in this key will contain all 1.0 gains. 12250 In other words, the map reported in this key is the remaining lens shading 12251 that needs to be applied on the RAW image to get images without lens shading 12252 artifacts. See android.request.maxNumOutputRaw for a list of RAW image 12253 formats. 12254 </details> 12255 <hal_details> 12256 The lens shading map calculation may depend on exposure and white balance statistics. 12257 When AE and AWB are in AUTO modes 12258 (android.control.aeMode `!=` OFF and android.control.awbMode `!=` OFF), the HAL 12259 may have all the information it need to generate most accurate lens shading map. When 12260 AE or AWB are in manual mode 12261 (android.control.aeMode `==` OFF or android.control.awbMode `==` OFF), the shading map 12262 may be adversely impacted by manual exposure or white balance parameters. To avoid 12263 generating unreliable shading map data, the HAL may choose to lock the shading map with 12264 the latest known good map generated when the AE and AWB are in AUTO modes. 12265 </hal_details> 12266 </entry> 12267 <entry name="predictedColorGains" type="float" 12268 visibility="hidden" 12269 deprecated="true" 12270 optional="true" 12271 type_notes="A 1D array of floats for 4 color channel gains" 12272 container="array"> 12273 <array> 12274 <size>4</size> 12275 </array> 12276 <description>The best-fit color channel gains calculated 12277 by the camera device's statistics units for the current output frame. 12278 </description> 12279 <deprecation_description> 12280 Never fully implemented or specified; do not use 12281 </deprecation_description> 12282 <details> 12283 This may be different than the gains used for this frame, 12284 since statistics processing on data from a new frame 12285 typically completes after the transform has already been 12286 applied to that frame. 12287 12288 The 4 channel gains are defined in Bayer domain, 12289 see android.colorCorrection.gains for details. 12290 12291 This value should always be calculated by the auto-white balance (AWB) block, 12292 regardless of the android.control.* current values. 12293 </details> 12294 </entry> 12295 <entry name="predictedColorTransform" type="rational" 12296 visibility="hidden" 12297 deprecated="true" 12298 optional="true" 12299 type_notes="3x3 rational matrix in row-major order" 12300 container="array"> 12301 <array> 12302 <size>3</size> 12303 <size>3</size> 12304 </array> 12305 <description>The best-fit color transform matrix estimate 12306 calculated by the camera device's statistics units for the current 12307 output frame.</description> 12308 <deprecation_description> 12309 Never fully implemented or specified; do not use 12310 </deprecation_description> 12311 <details>The camera device will provide the estimate from its 12312 statistics unit on the white balance transforms to use 12313 for the next frame. These are the values the camera device believes 12314 are the best fit for the current output frame. This may 12315 be different than the transform used for this frame, since 12316 statistics processing on data from a new frame typically 12317 completes after the transform has already been applied to 12318 that frame. 12319 12320 These estimates must be provided for all frames, even if 12321 capture settings and color transforms are set by the application. 12322 12323 This value should always be calculated by the auto-white balance (AWB) block, 12324 regardless of the android.control.* current values. 12325 </details> 12326 </entry> 12327 <entry name="sceneFlicker" type="byte" visibility="public" enum="true" 12328 hwlevel="full"> 12329 <enum> 12330 <value>NONE 12331 <notes>The camera device does not detect any flickering illumination 12332 in the current scene.</notes></value> 12333 <value>50HZ 12334 <notes>The camera device detects illumination flickering at 50Hz 12335 in the current scene.</notes></value> 12336 <value>60HZ 12337 <notes>The camera device detects illumination flickering at 60Hz 12338 in the current scene.</notes></value> 12339 </enum> 12340 <description>The camera device estimated scene illumination lighting 12341 frequency.</description> 12342 <details> 12343 Many light sources, such as most fluorescent lights, flicker at a rate 12344 that depends on the local utility power standards. This flicker must be 12345 accounted for by auto-exposure routines to avoid artifacts in captured images. 12346 The camera device uses this entry to tell the application what the scene 12347 illuminant frequency is. 12348 12349 When manual exposure control is enabled 12350 (`android.control.aeMode == OFF` or `android.control.mode == 12351 OFF`), the android.control.aeAntibandingMode doesn't perform 12352 antibanding, and the application can ensure it selects 12353 exposure times that do not cause banding issues by looking 12354 into this metadata field. See 12355 android.control.aeAntibandingMode for more details. 12356 12357 Reports NONE if there doesn't appear to be flickering illumination. 12358 </details> 12359 </entry> 12360 <clone entry="android.statistics.hotPixelMapMode" kind="controls"> 12361 </clone> 12362 <entry name="hotPixelMap" type="int32" visibility="public" 12363 type_notes="list of coordinates based on android.sensor.pixelArraySize" 12364 container="array" typedef="point"> 12365 <array> 12366 <size>2</size> 12367 <size>n</size> 12368 </array> 12369 <description> 12370 List of `(x, y)` coordinates of hot/defective pixels on the sensor. 12371 </description> 12372 <range> 12373 n <= number of pixels on the sensor. 12374 The `(x, y)` coordinates must be bounded by 12375 android.sensor.info.pixelArraySize. 12376 </range> 12377 <details> 12378 A coordinate `(x, y)` must lie between `(0, 0)`, and 12379 `(width - 1, height - 1)` (inclusive), which are the top-left and 12380 bottom-right of the pixel array, respectively. The width and 12381 height dimensions are given in android.sensor.info.pixelArraySize. 12382 This may include hot pixels that lie outside of the active array 12383 bounds given by android.sensor.info.activeArraySize. 12384 12385 For camera devices with the 12386 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 12387 capability or devices where 12388 {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 12389 lists android.sensor.pixelMode, 12390 android.sensor.info.pixelArraySizeMaximumResolution will be used as the 12391 pixel array size if the corresponding request sets android.sensor.pixelMode to 12392 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 12393 </details> 12394 <hal_details> 12395 A hotpixel map contains the coordinates of pixels on the camera 12396 sensor that do report valid values (usually due to defects in 12397 the camera sensor). This includes pixels that are stuck at certain 12398 values, or have a response that does not accurately encode the 12399 incoming light from the scene. 12400 12401 To avoid performance issues, there should be significantly fewer hot 12402 pixels than actual pixels on the camera sensor. 12403 </hal_details> 12404 <tag id="V1" /> 12405 <tag id="RAW" /> 12406 </entry> 12407 </dynamic> 12408 <controls> 12409 <entry name="lensShadingMapMode" type="byte" visibility="public" enum="true" hwlevel="full"> 12410 <enum> 12411 <value>OFF 12412 <notes>Do not include a lens shading map in the capture result.</notes></value> 12413 <value>ON 12414 <notes>Include a lens shading map in the capture result.</notes></value> 12415 </enum> 12416 <description>Whether the camera device will output the lens 12417 shading map in output result metadata.</description> 12418 <range>android.statistics.info.availableLensShadingMapModes</range> 12419 <details>When set to ON, 12420 android.statistics.lensShadingMap will be provided in 12421 the output result metadata. 12422 12423 ON is always supported on devices with the RAW capability. 12424 </details> 12425 <tag id="RAW" /> 12426 </entry> 12427 </controls> 12428 <dynamic> 12429 <clone entry="android.statistics.lensShadingMapMode" kind="controls"> 12430 </clone> 12431 </dynamic> 12432 <controls> 12433 <entry name="oisDataMode" type="byte" visibility="public" enum="true" hal_version="3.3"> 12434 <enum> 12435 <value>OFF 12436 <notes>Do not include OIS data in the capture result.</notes></value> 12437 <value>ON 12438 <notes>Include OIS data in the capture result.</notes> 12439 <sdk_notes>android.statistics.oisSamples provides OIS sample data in the 12440 output result metadata. 12441 </sdk_notes> 12442 <ndk_notes>android.statistics.oisTimestamps, android.statistics.oisXShifts, 12443 and android.statistics.oisYShifts provide OIS data in the output result metadata. 12444 </ndk_notes> 12445 </value> 12446 </enum> 12447 <description>A control for selecting whether optical stabilization (OIS) position 12448 information is included in output result metadata.</description> 12449 <range>android.statistics.info.availableOisDataModes</range> 12450 <details> 12451 Since optical image stabilization generally involves motion much faster than the duration 12452 of individual image exposure, multiple OIS samples can be included for a single capture 12453 result. For example, if the OIS reporting operates at 200 Hz, a typical camera operating 12454 at 30fps may have 6-7 OIS samples per capture result. This information can be combined 12455 with the rolling shutter skew to account for lens motion during image exposure in 12456 post-processing algorithms. 12457 </details> 12458 </entry> 12459 </controls> 12460 <dynamic> 12461 <clone entry="android.statistics.oisDataMode" kind="controls"> 12462 </clone> 12463 <entry name="oisTimestamps" type="int64" visibility="ndk_public" container="array" hal_version="3.3"> 12464 <array> 12465 <size>n</size> 12466 </array> 12467 <description> 12468 An array of timestamps of OIS samples, in nanoseconds. 12469 </description> 12470 <units>nanoseconds</units> 12471 <details> 12472 The array contains the timestamps of OIS samples. The timestamps are in the same 12473 timebase as and comparable to android.sensor.timestamp. 12474 </details> 12475 </entry> 12476 <entry name="oisXShifts" type="float" visibility="ndk_public" container="array" hal_version="3.3"> 12477 <array> 12478 <size>n</size> 12479 </array> 12480 <description> 12481 An array of shifts of OIS samples, in x direction. 12482 </description> 12483 <units>Pixels in active array.</units> 12484 <details> 12485 The array contains the amount of shifts in x direction, in pixels, based on OIS samples. 12486 A positive value is a shift from left to right in the pre-correction active array 12487 coordinate system. For example, if the optical center is (1000, 500) in pre-correction 12488 active array coordinates, a shift of (3, 0) puts the new optical center at (1003, 500). 12489 12490 The number of shifts must match the number of timestamps in 12491 android.statistics.oisTimestamps. 12492 12493 The OIS samples are not affected by whether lens distortion correction is enabled (on 12494 supporting devices). They are always reported in pre-correction active array coordinates, 12495 since the scaling of OIS shifts would depend on the specific spot on the sensor the shift 12496 is needed. 12497 </details> 12498 </entry> 12499 <entry name="oisYShifts" type="float" visibility="ndk_public" container="array" hal_version="3.3"> 12500 <array> 12501 <size>n</size> 12502 </array> 12503 <description> 12504 An array of shifts of OIS samples, in y direction. 12505 </description> 12506 <units>Pixels in active array.</units> 12507 <details> 12508 The array contains the amount of shifts in y direction, in pixels, based on OIS samples. 12509 A positive value is a shift from top to bottom in pre-correction active array coordinate 12510 system. For example, if the optical center is (1000, 500) in active array coordinates, a 12511 shift of (0, 5) puts the new optical center at (1000, 505). 12512 12513 The number of shifts must match the number of timestamps in 12514 android.statistics.oisTimestamps. 12515 12516 The OIS samples are not affected by whether lens distortion correction is enabled (on 12517 supporting devices). They are always reported in pre-correction active array coordinates, 12518 since the scaling of OIS shifts would depend on the specific spot on the sensor the shift 12519 is needed. 12520 </details> 12521 </entry> 12522 <entry name="oisSamples" type="float" visibility="java_public" synthetic="true" 12523 container="array" typedef="oisSample" hal_version="3.3"> 12524 <array> 12525 <size>n</size> 12526 </array> 12527 <description> 12528 An array of optical stabilization (OIS) position samples. 12529 </description> 12530 <details> 12531 Each OIS sample contains the timestamp and the amount of shifts in x and y direction, 12532 in pixels, of the OIS sample. 12533 12534 A positive value for a shift in x direction is a shift from left to right in the 12535 pre-correction active array coordinate system. For example, if the optical center is 12536 (1000, 500) in pre-correction active array coordinates, a shift of (3, 0) puts the new 12537 optical center at (1003, 500). 12538 12539 A positive value for a shift in y direction is a shift from top to bottom in 12540 pre-correction active array coordinate system. For example, if the optical center is 12541 (1000, 500) in active array coordinates, a shift of (0, 5) puts the new optical center at 12542 (1000, 505). 12543 12544 The OIS samples are not affected by whether lens distortion correction is enabled (on 12545 supporting devices). They are always reported in pre-correction active array coordinates, 12546 since the scaling of OIS shifts would depend on the specific spot on the sensor the shift 12547 is needed. 12548 </details> 12549 </entry> 12550 <entry name="lensIntrinsicsSamples" type="float" visibility="java_public" synthetic="true" 12551 container="array" typedef="lensIntrinsicsSample" 12552 hal_version="3.10"> 12553 <array> 12554 <size>n</size> 12555 </array> 12556 <description> 12557 An array of intra-frame lens intrinsic samples. 12558 </description> 12559 <details> 12560 Contains an array of intra-frame android.lens.intrinsicCalibration updates. This must 12561 not be confused or compared to android.statistics.oisSamples. Although OIS could be the 12562 main driver, all relevant factors such as focus distance and optical zoom must also 12563 be included. Do note that OIS samples must not be applied on top of the lens intrinsic 12564 samples. 12565 Support for this capture result can be queried via 12566 {@link android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys}. 12567 If available, clients can expect multiple samples per capture result. The specific 12568 amount will depend on current frame duration and sampling rate. Generally a sampling rate 12569 greater than or equal to 200Hz is considered sufficient for high quality results. 12570 </details> 12571 </entry> 12572 <entry name="lensIntrinsicTimestamps" type="int64" visibility="ndk_public" container="array" 12573 hal_version="3.10"> 12574 <array> 12575 <size>n</size> 12576 </array> 12577 <description> 12578 An array of timestamps of lens intrinsics samples, in nanoseconds. 12579 </description> 12580 <units>nanoseconds</units> 12581 <details> 12582 The array contains the timestamps of lens intrinsics samples. The timestamps are in the 12583 same timebase as and comparable to android.sensor.timestamp. 12584 </details> 12585 </entry> 12586 <entry name="lensIntrinsicSamples" type="float" visibility="ndk_public" 12587 container="array" hal_version="3.10"> 12588 <array> 12589 <size>5</size> 12590 <size>n</size> 12591 </array> 12592 <description> 12593 An array of intra-frame lens intrinsics. 12594 </description> 12595 <units> 12596 Pixels in the android.sensor.info.preCorrectionActiveArraySize coordinate system. 12597 </units> 12598 <details> 12599 The data layout and contents of individual array entries matches with 12600 android.lens.intrinsicCalibration. 12601 </details> 12602 </entry> 12603 </dynamic> 12604 </section> 12605 <section name="tonemap"> 12606 <controls> 12607 <entry name="curveBlue" type="float" visibility="ndk_public" 12608 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 12609 container="array" hwlevel="full"> 12610 <array> 12611 <size>n</size> 12612 <size>2</size> 12613 </array> 12614 <description>Tonemapping / contrast / gamma curve for the blue 12615 channel, to use when android.tonemap.mode is 12616 CONTRAST_CURVE.</description> 12617 <details>See android.tonemap.curveRed for more details.</details> 12618 </entry> 12619 <entry name="curveGreen" type="float" visibility="ndk_public" 12620 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 12621 container="array" hwlevel="full"> 12622 <array> 12623 <size>n</size> 12624 <size>2</size> 12625 </array> 12626 <description>Tonemapping / contrast / gamma curve for the green 12627 channel, to use when android.tonemap.mode is 12628 CONTRAST_CURVE.</description> 12629 <details>See android.tonemap.curveRed for more details.</details> 12630 </entry> 12631 <entry name="curveRed" type="float" visibility="ndk_public" 12632 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 12633 container="array" hwlevel="full"> 12634 <array> 12635 <size>n</size> 12636 <size>2</size> 12637 </array> 12638 <description>Tonemapping / contrast / gamma curve for the red 12639 channel, to use when android.tonemap.mode is 12640 CONTRAST_CURVE.</description> 12641 <range>0-1 on both input and output coordinates, normalized 12642 as a floating-point value such that 0 == black and 1 == white. 12643 </range> 12644 <details> 12645 Each channel's curve is defined by an array of control points: 12646 12647 android.tonemap.curveRed = 12648 [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ] 12649 2 <= N <= android.tonemap.maxCurvePoints 12650 12651 These are sorted in order of increasing `Pin`; it is 12652 required that input values 0.0 and 1.0 are included in the list to 12653 define a complete mapping. For input values between control points, 12654 the camera device must linearly interpolate between the control 12655 points. 12656 12657 Each curve can have an independent number of points, and the number 12658 of points can be less than max (that is, the request doesn't have to 12659 always provide a curve with number of points equivalent to 12660 android.tonemap.maxCurvePoints). 12661 12662 For devices with MONOCHROME capability, all three channels must have the same set of 12663 control points. 12664 12665 A few examples, and their corresponding graphical mappings; these 12666 only specify the red channel and the precision is limited to 4 12667 digits, for conciseness. 12668 12669 Linear mapping: 12670 12671 android.tonemap.curveRed = [ 0, 0, 1.0, 1.0 ] 12672 12673  12674 12675 Invert mapping: 12676 12677 android.tonemap.curveRed = [ 0, 1.0, 1.0, 0 ] 12678 12679  12680 12681 Gamma 1/2.2 mapping, with 16 control points: 12682 12683 android.tonemap.curveRed = [ 12684 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812, 12685 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072, 12686 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685, 12687 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ] 12688 12689  12690 12691 Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points: 12692 12693 android.tonemap.curveRed = [ 12694 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845, 12695 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130, 12696 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721, 12697 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ] 12698 12699  12700 </details> 12701 <hal_details> 12702 For good quality of mapping, at least 128 control points are 12703 preferred. 12704 12705 A typical use case of this would be a gamma-1/2.2 curve, with as many 12706 control points used as are available. 12707 </hal_details> 12708 </entry> 12709 <entry name="curve" type="float" visibility="java_public" synthetic="true" 12710 typedef="tonemapCurve" 12711 hwlevel="full"> 12712 <description>Tonemapping / contrast / gamma curve to use when android.tonemap.mode 12713 is CONTRAST_CURVE.</description> 12714 <details> 12715 The tonemapCurve consist of three curves for each of red, green, and blue 12716 channels respectively. The following example uses the red channel as an 12717 example. The same logic applies to green and blue channel. 12718 Each channel's curve is defined by an array of control points: 12719 12720 curveRed = 12721 [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ] 12722 2 <= N <= android.tonemap.maxCurvePoints 12723 12724 These are sorted in order of increasing `Pin`; it is always 12725 guaranteed that input values 0.0 and 1.0 are included in the list to 12726 define a complete mapping. For input values between control points, 12727 the camera device must linearly interpolate between the control 12728 points. 12729 12730 Each curve can have an independent number of points, and the number 12731 of points can be less than max (that is, the request doesn't have to 12732 always provide a curve with number of points equivalent to 12733 android.tonemap.maxCurvePoints). 12734 12735 For devices with MONOCHROME capability, all three channels must have the same set of 12736 control points. 12737 12738 A few examples, and their corresponding graphical mappings; these 12739 only specify the red channel and the precision is limited to 4 12740 digits, for conciseness. 12741 12742 Linear mapping: 12743 12744 curveRed = [ (0, 0), (1.0, 1.0) ] 12745 12746  12747 12748 Invert mapping: 12749 12750 curveRed = [ (0, 1.0), (1.0, 0) ] 12751 12752  12753 12754 Gamma 1/2.2 mapping, with 16 control points: 12755 12756 curveRed = [ 12757 (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812), 12758 (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072), 12759 (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685), 12760 (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ] 12761 12762  12763 12764 Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points: 12765 12766 curveRed = [ 12767 (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845), 12768 (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130), 12769 (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721), 12770 (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ] 12771 12772  12773 </details> 12774 <hal_details> 12775 This entry is created by the framework from the curveRed, curveGreen and 12776 curveBlue entries. 12777 </hal_details> 12778 </entry> 12779 <entry name="mode" type="byte" visibility="public" enum="true" 12780 hwlevel="full"> 12781 <enum> 12782 <value>CONTRAST_CURVE 12783 <notes>Use the tone mapping curve specified in 12784 the android.tonemap.curve* entries. 12785 12786 All color enhancement and tonemapping must be disabled, except 12787 for applying the tonemapping curve specified by 12788 android.tonemap.curve. 12789 12790 Must not slow down frame rate relative to raw 12791 sensor output. 12792 </notes> 12793 </value> 12794 <value>FAST 12795 <notes> 12796 Advanced gamma mapping and color enhancement may be applied, without 12797 reducing frame rate compared to raw sensor output. 12798 </notes> 12799 </value> 12800 <value>HIGH_QUALITY 12801 <notes> 12802 High-quality gamma mapping and color enhancement will be applied, at 12803 the cost of possibly reduced frame rate compared to raw sensor output. 12804 </notes> 12805 </value> 12806 <value>GAMMA_VALUE 12807 <notes> 12808 Use the gamma value specified in android.tonemap.gamma to perform 12809 tonemapping. 12810 12811 All color enhancement and tonemapping must be disabled, except 12812 for applying the tonemapping curve specified by android.tonemap.gamma. 12813 12814 Must not slow down frame rate relative to raw sensor output. 12815 </notes> 12816 </value> 12817 <value>PRESET_CURVE 12818 <notes> 12819 Use the preset tonemapping curve specified in 12820 android.tonemap.presetCurve to perform tonemapping. 12821 12822 All color enhancement and tonemapping must be disabled, except 12823 for applying the tonemapping curve specified by 12824 android.tonemap.presetCurve. 12825 12826 Must not slow down frame rate relative to raw sensor output. 12827 </notes> 12828 </value> 12829 </enum> 12830 <description>High-level global contrast/gamma/tonemapping control. 12831 </description> 12832 <range>android.tonemap.availableToneMapModes</range> 12833 <details> 12834 When switching to an application-defined contrast curve by setting 12835 android.tonemap.mode to CONTRAST_CURVE, the curve is defined 12836 per-channel with a set of `(in, out)` points that specify the 12837 mapping from input high-bit-depth pixel value to the output 12838 low-bit-depth value. Since the actual pixel ranges of both input 12839 and output may change depending on the camera pipeline, the values 12840 are specified by normalized floating-point numbers. 12841 12842 More-complex color mapping operations such as 3D color look-up 12843 tables, selective chroma enhancement, or other non-linear color 12844 transforms will be disabled when android.tonemap.mode is 12845 CONTRAST_CURVE. 12846 12847 When using either FAST or HIGH_QUALITY, the camera device will 12848 emit its own tonemap curve in android.tonemap.curve. 12849 These values are always available, and as close as possible to the 12850 actually used nonlinear/nonglobal transforms. 12851 12852 If a request is sent with CONTRAST_CURVE with the camera device's 12853 provided curve in FAST or HIGH_QUALITY, the image's tonemap will be 12854 roughly the same.</details> 12855 </entry> 12856 </controls> 12857 <static> 12858 <entry name="maxCurvePoints" type="int32" visibility="public" 12859 hwlevel="full"> 12860 <description>Maximum number of supported points in the 12861 tonemap curve that can be used for android.tonemap.curve. 12862 </description> 12863 <details> 12864 If the actual number of points provided by the application (in android.tonemap.curve*) is 12865 less than this maximum, the camera device will resample the curve to its internal 12866 representation, using linear interpolation. 12867 12868 The output curves in the result metadata may have a different number 12869 of points than the input curves, and will represent the actual 12870 hardware curves used as closely as possible when linearly interpolated. 12871 </details> 12872 <hal_details> 12873 This value must be at least 64. This should be at least 128. 12874 </hal_details> 12875 </entry> 12876 <entry name="availableToneMapModes" type="byte" visibility="public" 12877 type_notes="list of enums" container="array" typedef="enumList" hwlevel="full"> 12878 <array> 12879 <size>n</size> 12880 </array> 12881 <description> 12882 List of tonemapping modes for android.tonemap.mode that are supported by this camera 12883 device. 12884 </description> 12885 <range>Any value listed in android.tonemap.mode</range> 12886 <details> 12887 Camera devices that support the MANUAL_POST_PROCESSING capability will always contain 12888 at least one of below mode combinations: 12889 12890 * CONTRAST_CURVE, FAST and HIGH_QUALITY 12891 * GAMMA_VALUE, PRESET_CURVE, FAST and HIGH_QUALITY 12892 12893 This includes all FULL level devices. 12894 </details> 12895 <hal_details> 12896 HAL must support both FAST and HIGH_QUALITY if automatic tonemap control is available 12897 on the camera device, but the underlying implementation can be the same for both modes. 12898 That is, if the highest quality implementation on the camera device does not slow down 12899 capture rate, then FAST and HIGH_QUALITY will generate the same output. 12900 </hal_details> 12901 </entry> 12902 </static> 12903 <dynamic> 12904 <clone entry="android.tonemap.curveBlue" kind="controls"> 12905 </clone> 12906 <clone entry="android.tonemap.curveGreen" kind="controls"> 12907 </clone> 12908 <clone entry="android.tonemap.curveRed" kind="controls"> 12909 </clone> 12910 <clone entry="android.tonemap.curve" kind="controls"> 12911 </clone> 12912 <clone entry="android.tonemap.mode" kind="controls"> 12913 </clone> 12914 </dynamic> 12915 <controls> 12916 <entry name="gamma" type="float" visibility="public"> 12917 <description> Tonemapping curve to use when android.tonemap.mode is 12918 GAMMA_VALUE 12919 </description> 12920 <details> 12921 The tonemap curve will be defined the following formula: 12922 12923 * OUT = pow(IN, 1.0 / gamma) 12924 12925 where IN and OUT is the input pixel value scaled to range [0.0, 1.0], 12926 pow is the power function and gamma is the gamma value specified by this 12927 key. 12928 12929 The same curve will be applied to all color channels. The camera device 12930 may clip the input gamma value to its supported range. The actual applied 12931 value will be returned in capture result. 12932 12933 The valid range of gamma value varies on different devices, but values 12934 within [1.0, 5.0] are guaranteed not to be clipped. 12935 </details> 12936 </entry> 12937 <entry name="presetCurve" type="byte" visibility="public" enum="true"> 12938 <enum> 12939 <value>SRGB 12940 <notes>Tonemapping curve is defined by sRGB</notes> 12941 </value> 12942 <value>REC709 12943 <notes>Tonemapping curve is defined by ITU-R BT.709</notes> 12944 </value> 12945 </enum> 12946 <description> Tonemapping curve to use when android.tonemap.mode is 12947 PRESET_CURVE 12948 </description> 12949 <details> 12950 The tonemap curve will be defined by specified standard. 12951 12952 sRGB (approximated by 16 control points): 12953 12954  12955 12956 Rec. 709 (approximated by 16 control points): 12957 12958  12959 12960 Note that above figures show a 16 control points approximation of preset 12961 curves. Camera devices may apply a different approximation to the curve. 12962 </details> 12963 </entry> 12964 </controls> 12965 <dynamic> 12966 <clone entry="android.tonemap.gamma" kind="controls"> 12967 </clone> 12968 <clone entry="android.tonemap.presetCurve" kind="controls"> 12969 </clone> 12970 </dynamic> 12971 </section> 12972 <section name="led"> 12973 <controls> 12974 <entry name="transmit" type="byte" visibility="hidden" optional="true" 12975 enum="true" typedef="boolean"> 12976 <enum> 12977 <value>OFF</value> 12978 <value>ON</value> 12979 </enum> 12980 <description>This LED is nominally used to indicate to the user 12981 that the camera is powered on and may be streaming images back to the 12982 Application Processor. In certain rare circumstances, the OS may 12983 disable this when video is processed locally and not transmitted to 12984 any untrusted applications. 12985 12986 In particular, the LED *must* always be on when the data could be 12987 transmitted off the device. The LED *should* always be on whenever 12988 data is stored locally on the device. 12989 12990 The LED *may* be off if a trusted application is using the data that 12991 doesn't violate the above rules. 12992 </description> 12993 </entry> 12994 </controls> 12995 <dynamic> 12996 <clone entry="android.led.transmit" kind="controls"></clone> 12997 </dynamic> 12998 <static> 12999 <entry name="availableLeds" type="byte" visibility="hidden" optional="true" 13000 enum="true" 13001 container="array"> 13002 <array> 13003 <size>n</size> 13004 </array> 13005 <enum> 13006 <value>TRANSMIT 13007 <notes>android.led.transmit control is used.</notes> 13008 </value> 13009 </enum> 13010 <description>A list of camera LEDs that are available on this system. 13011 </description> 13012 </entry> 13013 </static> 13014 </section> 13015 <section name="info"> 13016 <static> 13017 <entry name="supportedHardwareLevel" type="byte" visibility="public" 13018 enum="true" hwlevel="legacy"> 13019 <enum> 13020 <value> 13021 LIMITED 13022 <notes> 13023 This camera device does not have enough capabilities to qualify as a `FULL` device or 13024 better. 13025 13026 Only the stream configurations listed in the `LEGACY` and `LIMITED` 13027 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#limited-level-additional-guaranteed-configurations) 13028 in the documentation are guaranteed to be supported. 13029 13030 All `LIMITED` devices support the `BACKWARDS_COMPATIBLE` capability, indicating basic 13031 support for color image capture. The only exception is that the device may 13032 alternatively support only the `DEPTH_OUTPUT` capability, if it can only output depth 13033 measurements and not color images. 13034 13035 `LIMITED` devices and above require the use of android.control.aePrecaptureTrigger 13036 to lock exposure metering (and calculate flash power, for cameras with flash) before 13037 capturing a high-quality still image. 13038 13039 A `LIMITED` device that only lists the `BACKWARDS_COMPATIBLE` capability is only 13040 required to support full-automatic operation and post-processing (`OFF` is not 13041 supported for android.control.aeMode, android.control.afMode, or 13042 android.control.awbMode) 13043 13044 Additional capabilities may optionally be supported by a `LIMITED`-level device, and 13045 can be checked for in android.request.availableCapabilities. 13046 </notes> 13047 </value> 13048 <value> 13049 FULL 13050 <notes> 13051 This camera device is capable of supporting advanced imaging applications. 13052 13053 The stream configurations listed in the `FULL`, `LEGACY` and `LIMITED` 13054 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#full-level-additional-guaranteed-configurations) 13055 in the documentation are guaranteed to be supported. 13056 13057 A `FULL` device will support below capabilities: 13058 13059 * `BURST_CAPTURE` capability (android.request.availableCapabilities contains 13060 `BURST_CAPTURE`) 13061 * Per frame control (android.sync.maxLatency `==` PER_FRAME_CONTROL) 13062 * Manual sensor control (android.request.availableCapabilities contains `MANUAL_SENSOR`) 13063 * Manual post-processing control (android.request.availableCapabilities contains 13064 `MANUAL_POST_PROCESSING`) 13065 * The required exposure time range defined in android.sensor.info.exposureTimeRange 13066 * The required maxFrameDuration defined in android.sensor.info.maxFrameDuration 13067 13068 Note: 13069 Pre-API level 23, FULL devices also supported arbitrary cropping region 13070 (android.scaler.croppingType `== FREEFORM`); this requirement was relaxed in API level 13071 23, and `FULL` devices may only support `CENTERED` cropping. 13072 </notes> 13073 </value> 13074 <value> 13075 LEGACY 13076 <notes> 13077 This camera device is running in backward compatibility mode. 13078 13079 Only the stream configurations listed in the `LEGACY` 13080 [table](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations) 13081 in the documentation are supported. 13082 13083 A `LEGACY` device does not support per-frame control, manual sensor control, manual 13084 post-processing, arbitrary cropping regions, and has relaxed performance constraints. 13085 No additional capabilities beyond `BACKWARD_COMPATIBLE` will ever be listed by a 13086 `LEGACY` device in android.request.availableCapabilities. 13087 13088 In addition, the android.control.aePrecaptureTrigger is not functional on `LEGACY` 13089 devices. Instead, every request that includes a JPEG-format output target is treated 13090 as triggering a still capture, internally executing a precapture trigger. This may 13091 fire the flash for flash power metering during precapture, and then fire the flash 13092 for the final capture, if a flash is available on the device and the AE mode is set to 13093 enable the flash. 13094 13095 Devices that initially shipped with Android version {@link 13096 android.os.Build.VERSION_CODES#Q Q} or newer will not include any LEGACY-level devices. 13097 </notes> 13098 </value> 13099 <value> 13100 3 13101 <notes> 13102 This camera device is capable of YUV reprocessing and RAW data capture, in addition to 13103 FULL-level capabilities. 13104 13105 The stream configurations listed in the `LEVEL_3`, `RAW`, `FULL`, `LEGACY` and 13106 `LIMITED` 13107 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#level-3-additional-guaranteed-configurations) 13108 in the documentation are guaranteed to be supported. 13109 13110 The following additional capabilities are guaranteed to be supported: 13111 13112 * `YUV_REPROCESSING` capability (android.request.availableCapabilities contains 13113 `YUV_REPROCESSING`) 13114 * `RAW` capability (android.request.availableCapabilities contains 13115 `RAW`) 13116 </notes> 13117 </value> 13118 <value hal_version="3.3"> 13119 EXTERNAL 13120 <notes> 13121 This camera device is backed by an external camera connected to this Android device. 13122 13123 The device has capability identical to a LIMITED level device, with the following 13124 exceptions: 13125 13126 * The device may not report lens/sensor related information such as 13127 - android.lens.focalLength 13128 - android.lens.info.hyperfocalDistance 13129 - android.sensor.info.physicalSize 13130 - android.sensor.info.whiteLevel 13131 - android.sensor.blackLevelPattern 13132 - android.sensor.info.colorFilterArrangement 13133 - android.sensor.rollingShutterSkew 13134 * The device will report 0 for android.sensor.orientation 13135 * The device has less guarantee on stable framerate, as the framerate partly depends 13136 on the external camera being used. 13137 </notes> 13138 </value> 13139 </enum> 13140 <description> 13141 Generally classifies the overall set of the camera device functionality. 13142 </description> 13143 <details> 13144 The supported hardware level is a high-level description of the camera device's 13145 capabilities, summarizing several capabilities into one field. Each level adds additional 13146 features to the previous one, and is always a strict superset of the previous level. 13147 The ordering is `LEGACY < LIMITED < FULL < LEVEL_3`. 13148 13149 Starting from `LEVEL_3`, the level enumerations are guaranteed to be in increasing 13150 numerical value as well. To check if a given device is at least at a given hardware level, 13151 the following code snippet can be used: 13152 13153 // Returns true if the device supports the required hardware level, or better. 13154 boolean isHardwareLevelSupported(CameraCharacteristics c, int requiredLevel) { 13155 final int[] sortedHwLevels = { 13156 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY, 13157 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL, 13158 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED, 13159 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL, 13160 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3 13161 }; 13162 int deviceLevel = c.get(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL); 13163 if (requiredLevel == deviceLevel) { 13164 return true; 13165 } 13166 13167 for (int sortedlevel : sortedHwLevels) { 13168 if (sortedlevel == requiredLevel) { 13169 return true; 13170 } else if (sortedlevel == deviceLevel) { 13171 return false; 13172 } 13173 } 13174 return false; // Should never reach here 13175 } 13176 13177 At a high level, the levels are: 13178 13179 * `LEGACY` devices operate in a backwards-compatibility mode for older 13180 Android devices, and have very limited capabilities. 13181 * `LIMITED` devices represent the 13182 baseline feature set, and may also include additional capabilities that are 13183 subsets of `FULL`. 13184 * `FULL` devices additionally support per-frame manual control of sensor, flash, lens and 13185 post-processing settings, and image capture at a high rate. 13186 * `LEVEL_3` devices additionally support YUV reprocessing and RAW image capture, along 13187 with additional output stream configurations. 13188 * `EXTERNAL` devices are similar to `LIMITED` devices with exceptions like some sensor or 13189 lens information not reported or less stable framerates. 13190 13191 See the individual level enums for full descriptions of the supported capabilities. The 13192 android.request.availableCapabilities entry describes the device's capabilities at a 13193 finer-grain level, if needed. In addition, many controls have their available settings or 13194 ranges defined in individual entries from {@link 13195 android.hardware.camera2.CameraCharacteristics|ACameraManager_getCameraCharacteristics}. 13196 13197 Some features are not part of any particular hardware level or capability and must be 13198 queried separately. These include: 13199 13200 * Calibrated timestamps (android.sensor.info.timestampSource `==` REALTIME) 13201 * Precision lens control (android.lens.info.focusDistanceCalibration `==` CALIBRATED) 13202 * Face detection (android.statistics.info.availableFaceDetectModes) 13203 * Optical or electrical image stabilization 13204 (android.lens.info.availableOpticalStabilization, 13205 android.control.availableVideoStabilizationModes) 13206 13207 </details> 13208 <hal_details> 13209 A camera HALv3 device can implement one of three possible operational modes; LIMITED, 13210 FULL, and LEVEL_3. 13211 13212 FULL support or better is expected from new higher-end devices. Limited 13213 mode has hardware requirements roughly in line with those for a camera HAL device v1 13214 implementation, and is expected from older or inexpensive devices. Each level is a strict 13215 superset of the previous level, and they share the same essential operational flow. 13216 13217 For full details refer to "S3. Operational Modes" in camera3.h 13218 13219 Camera HAL3+ must not implement LEGACY mode. It is there for backwards compatibility in 13220 the `android.hardware.camera2` user-facing API only on legacy HALv1 devices, and is 13221 implemented by the camera framework code. 13222 13223 EXTERNAL level devices have lower performance bar in CTS since the performance might depend 13224 on the external camera being used and is not fully controlled by the device manufacturer. 13225 The ITS test suite is exempted for the same reason. 13226 </hal_details> 13227 </entry> 13228 <entry name="version" type="byte" visibility="public" typedef="string" hal_version="3.3"> 13229 <description> 13230 A short string for manufacturer version information about the camera device, such as 13231 ISP hardware, sensors, etc. 13232 </description> 13233 <details> 13234 This can be used in {@link android.media.ExifInterface#TAG_IMAGE_DESCRIPTION TAG_IMAGE_DESCRIPTION} 13235 in jpeg EXIF. This key may be absent if no version information is available on the 13236 device. 13237 </details> 13238 <hal_details> 13239 The string must consist of only alphanumeric characters, punctuation, and 13240 whitespace, i.e. it must match regular expression "[\p{Alnum}\p{Punct}\p{Space}]*". 13241 It must not exceed 256 characters. 13242 </hal_details> 13243 </entry> 13244 <entry name="supportedBufferManagementVersion" type="byte" visibility="system" 13245 enum="true" hal_version="3.4"> 13246 <enum> 13247 <value> 13248 HIDL_DEVICE_3_5 13249 <notes> 13250 This camera device supports and opts in to the buffer management APIs provided by 13251 HIDL ICameraDevice version 3.5. 13252 </notes> 13253 </value> 13254 <value hal_version="3.10"> 13255 SESSION_CONFIGURABLE 13256 <notes> 13257 This camera device supports the buffer management APIs provided by AIDL ICameraDevice 13258 version 1. It also supports the ICameraDeviceSession.configureStreamsV2 call to 13259 inform the camera framework whether HAL buffer manager must be used for the 13260 particular session configured. 13261 </notes> 13262 </value> 13263 </enum> 13264 <description> 13265 The version of buffer management API this camera device supports and opts into. 13266 </description> 13267 <details> 13268 When this key is not present, camera framework will interact with this camera device 13269 without any buffer management HAL API. When this key is present and camera framework 13270 supports the buffer management API version, camera framework will interact with camera 13271 HAL using such version of buffer management API. 13272 </details> 13273 </entry> 13274 <entry name="deviceStateSensorOrientationMap" type="int64" visibility="java_public" 13275 synthetic="true" optional="true" typedef="deviceStateSensorOrientationMap" 13276 hwlevel="limited"> 13277 <description>This lists the mapping between a device folding state and 13278 specific camera sensor orientation for logical cameras on a foldable device. 13279 </description> 13280 <details> 13281 Logical cameras on foldable devices can support sensors with different orientation 13282 values. The orientation value may need to change depending on the specific folding 13283 state. Information about the mapping between the device folding state and the 13284 sensor orientation can be obtained in 13285 {@link android.hardware.camera2.params.DeviceStateSensorOrientationMap}. 13286 Device state orientation maps are optional and maybe present on devices that support 13287 android.scaler.rotateAndCrop. 13288 </details> 13289 </entry> 13290 <entry name="deviceStateOrientations" type="int64" visibility="ndk_public" 13291 container="array" hwlevel="limited" hal_version="3.7"> 13292 <array> 13293 <size>2</size> 13294 <size>n</size> 13295 </array> 13296 <units>(device fold state, sensor orientation) x n</units> 13297 <details> 13298 HAL must populate the array with 13299 (hardware::camera::provider::V2_5::DeviceState, sensorOrientation) pairs for each 13300 supported device state bitwise combination. 13301 </details> 13302 </entry> 13303 <entry name="sessionConfigurationQueryVersion" type="int32" 13304 visibility="fwk_java_public" enum="true" typedef="versionCode" 13305 hwlevel="legacy" hal_version="3.10"> 13306 <enum> 13307 <value id="34">UPSIDE_DOWN_CAKE</value> 13308 <value id="35">VANILLA_ICE_CREAM</value> 13309 <value id="36" hal_version="3.11">BAKLAVA</value> 13310 </enum> 13311 <description>The version of the session configuration query 13312 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#isSessionConfigurationSupported} 13313 and {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#getSessionCharacteristics} 13314 APIs. 13315 </description> 13316 <details>The possible values in this key correspond to the values defined in 13317 android.os.Build.VERSION_CODES. Each version defines a set of feature combinations the 13318 camera device must reliably report whether they are supported via 13319 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#isSessionConfigurationSupported}. 13320 It also defines the set of session specific keys in CameraCharacteristics when returned from 13321 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#getSessionCharacteristics}. 13322 The version is always less or equal to android.os.Build.VERSION.SDK_INT. 13323 13324 If set to UPSIDE_DOWN_CAKE, this camera device doesn't support the 13325 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup} API. 13326 Trying to create a CameraDeviceSetup instance throws an UnsupportedOperationException. 13327 13328 From VANILLA_ICE_CREAM onwards, the camera compliance tests verify a set of 13329 commonly used SessionConfigurations to ensure that the outputs of 13330 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#isSessionConfigurationSupported} 13331 and {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#getSessionCharacteristics} 13332 are accurate. The application is encouraged to use these SessionConfigurations when turning on 13333 multiple features at the same time. 13334 13335 When set to VANILLA_ICE_CREAM, the combinations of the following configurations are verified 13336 by the compliance tests: 13337 13338 * A set of commonly used stream combinations: 13339 13340 Target 1 | Size | Target 2 | Size | 13341 :----------:|:-------------:|:---------------:|:------------:| 13342 PRIV | S1080P | | | 13343 PRIV | S720P | | | 13344 PRIV | S1080P | JPEG/JPEG_R | MAXIMUM_16_9 | 13345 PRIV | S1080P | JPEG/JPEG_R | UHD | 13346 PRIV | S1080P | JPEG/JPEG_R | S1440P | 13347 PRIV | S1080P | JPEG/JPEG_R | S1080P | 13348 PRIV | S1080P | PRIV | UHD | 13349 PRIV | S720P | JPEG/JPEG_R | MAXIMUM_16_9 | 13350 PRIV | S720P | JPEG/JPEG_R | UHD | 13351 PRIV | S720P | JPEG/JPEG_R | S1080P | 13352 PRIV | XVGA | JPEG/JPEG_R | MAXIMUM_4_3 | 13353 PRIV | S1080P_4_3 | JPEG/JPEG_R | MAXIMUM_4_3 | 13354 13355 * {@code MAXIMUM_4_3} refers to the camera device's maximum output resolution with 13356 4:3 aspect ratio for that format from {@code StreamConfigurationMap#getOutputSizes}. 13357 * {@code MAXIMUM_16_9} is the maximum output resolution with 16:9 aspect ratio. 13358 * {@code S1440P} refers to {@code 2560x1440 (16:9)}. 13359 * {@code S1080P} refers to {@code 1920x1080 (16:9)}. 13360 * {@code S720P} refers to {@code 1280x720 (16:9)}. 13361 * {@code UHD} refers to {@code 3840x2160 (16:9)}. 13362 * {@code XVGA} refers to {@code 1024x768 (4:3)}. 13363 * {@code S1080P_43} refers to {@code 1440x1080 (4:3)}. 13364 13365 * VIDEO_STABILIZATION_MODE: {OFF, PREVIEW} 13366 13367 * AE_TARGET_FPS_RANGE: { {\*, 30}, {\*, 60} } 13368 13369 * DYNAMIC_RANGE_PROFILE: {STANDARD, HLG10} 13370 13371 All of the above configurations can be set up with a SessionConfiguration. The list of 13372 OutputConfiguration contains the stream configurations and DYNAMIC_RANGE_PROFILE, and 13373 the AE_TARGET_FPS_RANGE and VIDEO_STABILIZATION_MODE are set as session parameters. 13374 13375 When set to BAKLAVA, the additional stream combinations below are verified 13376 by the compliance tests: 13377 13378 Target 1 | Size | Target 2 | Size | 13379 :----------:|:-------------:|:---------------:|:------------:| 13380 PRIV | S1080P | PRIV | S1080P | 13381 PRIV | S1080P | PRIV | S1440P | 13382 13383 </details> 13384 <hal_details> 13385 Preview stabilization must be orthogonal to other features. In other words, if preview 13386 stabilization is supported by the camera device, the return value of 13387 isStreamCombinationWithSettingsSupported for a particular combination must return 13388 the same value between stabilization off and preview stabilization on. This reduces the 13389 search space for feature combination queries. 13390 </hal_details> 13391 </entry> 13392 <entry name="deviceId" type="int32" visibility="fwk_only"> 13393 <description> 13394 Id of the device that owns this camera. 13395 </description> 13396 <details> 13397 In case of a virtual camera, this would be the id of the virtual device 13398 owning the camera. For any other camera, this key would not be present. 13399 Callers should assume {@link android.content.Context#DEVICE_ID_DEFAULT} 13400 in case this key is not present. 13401 </details> 13402 </entry> 13403 </static> 13404 </section> 13405 <section name="blackLevel"> 13406 <controls> 13407 <entry name="lock" type="byte" visibility="public" enum="true" 13408 typedef="boolean" hwlevel="full"> 13409 <enum> 13410 <value>OFF</value> 13411 <value>ON</value> 13412 </enum> 13413 <description> Whether black-level compensation is locked 13414 to its current values, or is free to vary.</description> 13415 <details>When set to `true` (ON), the values used for black-level 13416 compensation will not change until the lock is set to 13417 `false` (OFF). 13418 13419 Since changes to certain capture parameters (such as 13420 exposure time) may require resetting of black level 13421 compensation, the camera device must report whether setting 13422 the black level lock was successful in the output result 13423 metadata. 13424 13425 For example, if a sequence of requests is as follows: 13426 13427 * Request 1: Exposure = 10ms, Black level lock = OFF 13428 * Request 2: Exposure = 10ms, Black level lock = ON 13429 * Request 3: Exposure = 10ms, Black level lock = ON 13430 * Request 4: Exposure = 20ms, Black level lock = ON 13431 * Request 5: Exposure = 20ms, Black level lock = ON 13432 * Request 6: Exposure = 20ms, Black level lock = ON 13433 13434 And the exposure change in Request 4 requires the camera 13435 device to reset the black level offsets, then the output 13436 result metadata is expected to be: 13437 13438 * Result 1: Exposure = 10ms, Black level lock = OFF 13439 * Result 2: Exposure = 10ms, Black level lock = ON 13440 * Result 3: Exposure = 10ms, Black level lock = ON 13441 * Result 4: Exposure = 20ms, Black level lock = OFF 13442 * Result 5: Exposure = 20ms, Black level lock = ON 13443 * Result 6: Exposure = 20ms, Black level lock = ON 13444 13445 This indicates to the application that on frame 4, black 13446 levels were reset due to exposure value changes, and pixel 13447 values may not be consistent across captures. 13448 13449 The camera device will maintain the lock to the extent 13450 possible, only overriding the lock to OFF when changes to 13451 other request parameters require a black level recalculation 13452 or reset. 13453 </details> 13454 <hal_details> 13455 If for some reason black level locking is no longer possible 13456 (for example, the analog gain has changed, which forces 13457 black level offsets to be recalculated), then the HAL must 13458 override this request (and it must report 'OFF' when this 13459 does happen) until the next capture for which locking is 13460 possible again.</hal_details> 13461 <tag id="HAL2" /> 13462 </entry> 13463 </controls> 13464 <dynamic> 13465 <clone entry="android.blackLevel.lock" 13466 kind="controls"> 13467 <details> 13468 Whether the black level offset was locked for this frame. Should be 13469 ON if android.blackLevel.lock was ON in the capture request, unless 13470 a change in other capture settings forced the camera device to 13471 perform a black level reset. 13472 </details> 13473 </clone> 13474 </dynamic> 13475 </section> 13476 <section name="sync"> 13477 <dynamic> 13478 <entry name="frameNumber" type="int64" visibility="ndk_public" 13479 enum="true" hwlevel="legacy"> 13480 <enum> 13481 <value id="-1">CONVERGING 13482 <notes> 13483 The current result is not yet fully synchronized to any request. 13484 13485 Synchronization is in progress, and reading metadata from this 13486 result may include a mix of data that have taken effect since the 13487 last synchronization time. 13488 13489 In some future result, within android.sync.maxLatency frames, 13490 this value will update to the actual frame number frame number 13491 the result is guaranteed to be synchronized to (as long as the 13492 request settings remain constant). 13493 </notes> 13494 </value> 13495 <value id="-2">UNKNOWN 13496 <notes> 13497 The current result's synchronization status is unknown. 13498 13499 The result may have already converged, or it may be in 13500 progress. Reading from this result may include some mix 13501 of settings from past requests. 13502 13503 After a settings change, the new settings will eventually all 13504 take effect for the output buffers and results. However, this 13505 value will not change when that happens. Altering settings 13506 rapidly may provide outcomes using mixes of settings from recent 13507 requests. 13508 13509 This value is intended primarily for backwards compatibility with 13510 the older camera implementations (for android.hardware.Camera). 13511 </notes> 13512 </value> 13513 </enum> 13514 <description>The frame number corresponding to the last request 13515 with which the output result (metadata + buffers) has been fully 13516 synchronized.</description> 13517 <range>Either a non-negative value corresponding to a 13518 `frame_number`, or one of the two enums (CONVERGING / UNKNOWN). 13519 </range> 13520 <details> 13521 When a request is submitted to the camera device, there is usually a 13522 delay of several frames before the controls get applied. A camera 13523 device may either choose to account for this delay by implementing a 13524 pipeline and carefully submit well-timed atomic control updates, or 13525 it may start streaming control changes that span over several frame 13526 boundaries. 13527 13528 In the latter case, whenever a request's settings change relative to 13529 the previous submitted request, the full set of changes may take 13530 multiple frame durations to fully take effect. Some settings may 13531 take effect sooner (in less frame durations) than others. 13532 13533 While a set of control changes are being propagated, this value 13534 will be CONVERGING. 13535 13536 Once it is fully known that a set of control changes have been 13537 finished propagating, and the resulting updated control settings 13538 have been read back by the camera device, this value will be set 13539 to a non-negative frame number (corresponding to the request to 13540 which the results have synchronized to). 13541 13542 Older camera device implementations may not have a way to detect 13543 when all camera controls have been applied, and will always set this 13544 value to UNKNOWN. 13545 13546 FULL capability devices will always have this value set to the 13547 frame number of the request corresponding to this result. 13548 13549 _Further details_: 13550 13551 * Whenever a request differs from the last request, any future 13552 results not yet returned may have this value set to CONVERGING (this 13553 could include any in-progress captures not yet returned by the camera 13554 device, for more details see pipeline considerations below). 13555 * Submitting a series of multiple requests that differ from the 13556 previous request (e.g. r1, r2, r3 s.t. r1 != r2 != r3) 13557 moves the new synchronization frame to the last non-repeating 13558 request (using the smallest frame number from the contiguous list of 13559 repeating requests). 13560 * Submitting the same request repeatedly will not change this value 13561 to CONVERGING, if it was already a non-negative value. 13562 * When this value changes to non-negative, that means that all of the 13563 metadata controls from the request have been applied, all of the 13564 metadata controls from the camera device have been read to the 13565 updated values (into the result), and all of the graphics buffers 13566 corresponding to this result are also synchronized to the request. 13567 13568 _Pipeline considerations_: 13569 13570 Submitting a request with updated controls relative to the previously 13571 submitted requests may also invalidate the synchronization state 13572 of all the results corresponding to currently in-flight requests. 13573 13574 In other words, results for this current request and up to 13575 android.request.pipelineMaxDepth prior requests may have their 13576 android.sync.frameNumber change to CONVERGING. 13577 </details> 13578 <hal_details> 13579 Using UNKNOWN here is illegal unless android.sync.maxLatency 13580 is also UNKNOWN. 13581 13582 FULL capability devices should simply set this value to the 13583 `frame_number` of the request this result corresponds to. 13584 </hal_details> 13585 <tag id="V1" /> 13586 </entry> 13587 </dynamic> 13588 <static> 13589 <entry name="maxLatency" type="int32" visibility="public" enum="true" 13590 hwlevel="legacy"> 13591 <enum> 13592 <value id="0">PER_FRAME_CONTROL 13593 <notes> 13594 Every frame has the requests immediately applied. 13595 13596 Changing controls over multiple requests one after another will 13597 produce results that have those controls applied atomically 13598 each frame. 13599 13600 All FULL capability devices will have this as their maxLatency. 13601 </notes> 13602 </value> 13603 <value id="-1">UNKNOWN 13604 <notes> 13605 Each new frame has some subset (potentially the entire set) 13606 of the past requests applied to the camera settings. 13607 13608 By submitting a series of identical requests, the camera device 13609 will eventually have the camera settings applied, but it is 13610 unknown when that exact point will be. 13611 13612 All LEGACY capability devices will have this as their maxLatency. 13613 </notes> 13614 </value> 13615 </enum> 13616 <description> 13617 The maximum number of frames that can occur after a request 13618 (different than the previous) has been submitted, and before the 13619 result's state becomes synchronized. 13620 </description> 13621 <units>Frame counts</units> 13622 <range>A positive value, PER_FRAME_CONTROL, or UNKNOWN.</range> 13623 <details> 13624 This defines the maximum distance (in number of metadata results), 13625 between the frame number of the request that has new controls to apply 13626 and the frame number of the result that has all the controls applied. 13627 13628 In other words this acts as an upper boundary for how many frames 13629 must occur before the camera device knows for a fact that the new 13630 submitted camera settings have been applied in outgoing frames. 13631 </details> 13632 <hal_details> 13633 For example if maxLatency was 2, 13634 13635 initial request = X (repeating) 13636 request1 = X 13637 request2 = Y 13638 request3 = Y 13639 request4 = Y 13640 13641 where requestN has frameNumber N, and the first of the repeating 13642 initial request's has frameNumber F (and F < 1). 13643 13644 initial result = X' + { android.sync.frameNumber == F } 13645 result1 = X' + { android.sync.frameNumber == F } 13646 result2 = X' + { android.sync.frameNumber == CONVERGING } 13647 result3 = X' + { android.sync.frameNumber == CONVERGING } 13648 result4 = X' + { android.sync.frameNumber == 2 } 13649 13650 where resultN has frameNumber N. 13651 13652 Since `result4` has a `frameNumber == 4` and 13653 `android.sync.frameNumber == 2`, the distance is clearly 13654 `4 - 2 = 2`. 13655 13656 Use `frame_count` from camera3_request_t instead of 13657 android.request.frameCount or 13658 `{@link android.hardware.camera2.CaptureResult#getFrameNumber}`. 13659 13660 LIMITED devices are strongly encouraged to use a non-negative 13661 value. If UNKNOWN is used here then app developers do not have a way 13662 to know when sensor settings have been applied. 13663 </hal_details> 13664 <tag id="V1" /> 13665 </entry> 13666 </static> 13667 </section> 13668 <section name="reprocess"> 13669 <controls> 13670 <entry name="effectiveExposureFactor" type="float" visibility="java_public" hwlevel="limited"> 13671 <description> 13672 The amount of exposure time increase factor applied to the original output 13673 frame by the application processing before sending for reprocessing. 13674 </description> 13675 <units>Relative exposure time increase factor.</units> 13676 <range> &gt;= 1.0</range> 13677 <details> 13678 This is optional, and will be supported if the camera device supports YUV_REPROCESSING 13679 capability (android.request.availableCapabilities contains YUV_REPROCESSING). 13680 13681 For some YUV reprocessing use cases, the application may choose to filter the original 13682 output frames to effectively reduce the noise to the same level as a frame that was 13683 captured with longer exposure time. To be more specific, assuming the original captured 13684 images were captured with a sensitivity of S and an exposure time of T, the model in 13685 the camera device is that the amount of noise in the image would be approximately what 13686 would be expected if the original capture parameters had been a sensitivity of 13687 S/effectiveExposureFactor and an exposure time of T*effectiveExposureFactor, rather 13688 than S and T respectively. If the captured images were processed by the application 13689 before being sent for reprocessing, then the application may have used image processing 13690 algorithms and/or multi-frame image fusion to reduce the noise in the 13691 application-processed images (input images). By using the effectiveExposureFactor 13692 control, the application can communicate to the camera device the actual noise level 13693 improvement in the application-processed image. With this information, the camera 13694 device can select appropriate noise reduction and edge enhancement parameters to avoid 13695 excessive noise reduction (android.noiseReduction.mode) and insufficient edge 13696 enhancement (android.edge.mode) being applied to the reprocessed frames. 13697 13698 For example, for multi-frame image fusion use case, the application may fuse 13699 multiple output frames together to a final frame for reprocessing. When N image are 13700 fused into 1 image for reprocessing, the exposure time increase factor could be up to 13701 square root of N (based on a simple photon shot noise model). The camera device will 13702 adjust the reprocessing noise reduction and edge enhancement parameters accordingly to 13703 produce the best quality images. 13704 13705 This is relative factor, 1.0 indicates the application hasn't processed the input 13706 buffer in a way that affects its effective exposure time. 13707 13708 This control is only effective for YUV reprocessing capture request. For noise 13709 reduction reprocessing, it is only effective when `android.noiseReduction.mode != OFF`. 13710 Similarly, for edge enhancement reprocessing, it is only effective when 13711 `android.edge.mode != OFF`. 13712 </details> 13713 <tag id="REPROC" /> 13714 </entry> 13715 </controls> 13716 <dynamic> 13717 <clone entry="android.reprocess.effectiveExposureFactor" kind="controls"> 13718 </clone> 13719 </dynamic> 13720 <static> 13721 <entry name="maxCaptureStall" type="int32" visibility="java_public" hwlevel="limited"> 13722 <description> 13723 The maximal camera capture pipeline stall (in unit of frame count) introduced by a 13724 reprocess capture request. 13725 </description> 13726 <units>Number of frames.</units> 13727 <range> &lt;= 4</range> 13728 <details> 13729 The key describes the maximal interference that one reprocess (input) request 13730 can introduce to the camera simultaneous streaming of regular (output) capture 13731 requests, including repeating requests. 13732 13733 When a reprocessing capture request is submitted while a camera output repeating request 13734 (e.g. preview) is being served by the camera device, it may preempt the camera capture 13735 pipeline for at least one frame duration so that the camera device is unable to process 13736 the following capture request in time for the next sensor start of exposure boundary. 13737 When this happens, the application may observe a capture time gap (longer than one frame 13738 duration) between adjacent capture output frames, which usually exhibits as preview 13739 glitch if the repeating request output targets include a preview surface. This key gives 13740 the worst-case number of frame stall introduced by one reprocess request with any kind of 13741 formats/sizes combination. 13742 13743 If this key reports 0, it means a reprocess request doesn't introduce any glitch to the 13744 ongoing camera repeating request outputs, as if this reprocess request is never issued. 13745 13746 This key is supported if the camera device supports PRIVATE or YUV reprocessing ( 13747 i.e. android.request.availableCapabilities contains PRIVATE_REPROCESSING or 13748 YUV_REPROCESSING). 13749 </details> 13750 <tag id="REPROC" /> 13751 </entry> 13752 </static> 13753 </section> 13754 <section name="depth"> 13755 <static> 13756 <entry name="maxDepthSamples" type="int32" visibility="system" hwlevel="limited"> 13757 <description>Maximum number of points that a depth point cloud may contain. 13758 </description> 13759 <details> 13760 If a camera device supports outputting depth range data in the form of a depth point 13761 cloud ({@link android.graphics.ImageFormat#DEPTH_POINT_CLOUD}), this is the maximum 13762 number of points an output buffer may contain. 13763 13764 Any given buffer may contain between 0 and maxDepthSamples points, inclusive. 13765 If output in the depth point cloud format is not supported, this entry will 13766 not be defined. 13767 </details> 13768 <tag id="DEPTH" /> 13769 </entry> 13770 <entry name="availableDepthStreamConfigurations" type="int32" visibility="ndk_public" 13771 enum="true" container="array" typedef="streamConfiguration" hwlevel="limited"> 13772 <array> 13773 <size>n</size> 13774 <size>4</size> 13775 </array> 13776 <enum> 13777 <value>OUTPUT</value> 13778 <value>INPUT</value> 13779 </enum> 13780 <description>The available depth dataspace stream 13781 configurations that this camera device supports 13782 (i.e. format, width, height, output/input stream). 13783 </description> 13784 <details> 13785 These are output stream configurations for use with 13786 dataSpace HAL_DATASPACE_DEPTH. The configurations are 13787 listed as `(format, width, height, input?)` tuples. 13788 13789 Only devices that support depth output for at least 13790 the HAL_PIXEL_FORMAT_Y16 dense depth map may include 13791 this entry. 13792 13793 A device that also supports the HAL_PIXEL_FORMAT_BLOB 13794 sparse depth point cloud must report a single entry for 13795 the format in this list as `(HAL_PIXEL_FORMAT_BLOB, 13796 android.depth.maxDepthSamples, 1, OUTPUT)` in addition to 13797 the entries for HAL_PIXEL_FORMAT_Y16. 13798 </details> 13799 <tag id="DEPTH" /> 13800 </entry> 13801 <entry name="availableDepthMinFrameDurations" type="int64" visibility="ndk_public" 13802 container="array" typedef="streamConfigurationDuration" hwlevel="limited"> 13803 <array> 13804 <size>4</size> 13805 <size>n</size> 13806 </array> 13807 <description>This lists the minimum frame duration for each 13808 format/size combination for depth output formats. 13809 </description> 13810 <units>(format, width, height, ns) x n</units> 13811 <details> 13812 This should correspond to the frame duration when only that 13813 stream is active, with all processing (typically in android.*.mode) 13814 set to either OFF or FAST. 13815 13816 When multiple streams are used in a request, the minimum frame 13817 duration will be max(individual stream min durations). 13818 13819 The minimum frame duration of a stream (of a particular format, size) 13820 is the same regardless of whether the stream is input or output. 13821 13822 See android.sensor.frameDuration and 13823 android.scaler.availableStallDurations for more details about 13824 calculating the max frame rate. 13825 </details> 13826 <tag id="DEPTH" /> 13827 </entry> 13828 <entry name="availableDepthStallDurations" type="int64" visibility="ndk_public" 13829 container="array" typedef="streamConfigurationDuration" hwlevel="limited"> 13830 <array> 13831 <size>4</size> 13832 <size>n</size> 13833 </array> 13834 <description>This lists the maximum stall duration for each 13835 output format/size combination for depth streams. 13836 </description> 13837 <units>(format, width, height, ns) x n</units> 13838 <details> 13839 A stall duration is how much extra time would get added 13840 to the normal minimum frame duration for a repeating request 13841 that has streams with non-zero stall. 13842 13843 This functions similarly to 13844 android.scaler.availableStallDurations for depth 13845 streams. 13846 13847 All depth output stream formats may have a nonzero stall 13848 duration. 13849 </details> 13850 <tag id="DEPTH" /> 13851 </entry> 13852 <entry name="depthIsExclusive" type="byte" visibility="public" 13853 enum="true" typedef="boolean" hwlevel="limited"> 13854 <enum> 13855 <value>FALSE</value> 13856 <value>TRUE</value> 13857 </enum> 13858 <description>Indicates whether a capture request may target both a 13859 DEPTH16 / DEPTH_POINT_CLOUD output, and normal color outputs (such as 13860 YUV_420_888, JPEG, or RAW) simultaneously. 13861 </description> 13862 <details> 13863 If TRUE, including both depth and color outputs in a single 13864 capture request is not supported. An application must interleave color 13865 and depth requests. If FALSE, a single request can target both types 13866 of output. 13867 13868 Typically, this restriction exists on camera devices that 13869 need to emit a specific pattern or wavelength of light to 13870 measure depth values, which causes the color image to be 13871 corrupted during depth measurement. 13872 </details> 13873 </entry> 13874 <entry name="availableRecommendedDepthStreamConfigurations" type="int32" 13875 visibility="ndk_public" optional="true" container="array" 13876 typedef="recommendedStreamConfiguration" hal_version="3.4"> 13877 <array> 13878 <size>n</size> 13879 <size>5</size> 13880 </array> 13881 <description>Recommended depth stream configurations for common client use cases. 13882 </description> 13883 <details>Optional subset of the android.depth.availableDepthStreamConfigurations that 13884 contains similar tuples listed as 13885 (i.e. width, height, format, output/input stream, usecase bit field). 13886 Camera devices will be able to suggest particular depth stream configurations which are 13887 power and performance efficient for specific use cases. For more information about 13888 retrieving the suggestions see 13889 {@link android.hardware.camera2.CameraCharacteristics#getRecommendedStreamConfigurationMap}. 13890 </details> 13891 <ndk_details> 13892 For data representation please refer to 13893 android.scaler.availableRecommendedStreamConfigurations 13894 </ndk_details> 13895 <hal_details> 13896 Recommended depth configurations are expected to be declared with SNAPSHOT and/or 13897 ZSL if supported by the device. 13898 For additional details on how to declare recommended stream configurations, check 13899 android.scaler.availableRecommendedStreamConfigurations. 13900 For additional requirements on depth streams please consider 13901 android.depth.availableDepthStreamConfigurations. 13902 </hal_details> 13903 </entry> 13904 <entry name="availableDynamicDepthStreamConfigurations" type="int32" visibility="ndk_public" 13905 enum="true" container="array" typedef="streamConfiguration" hal_version="3.4"> 13906 <array> 13907 <size>n</size> 13908 <size>4</size> 13909 </array> 13910 <enum> 13911 <value>OUTPUT</value> 13912 <value>INPUT</value> 13913 </enum> 13914 <description>The available dynamic depth dataspace stream 13915 configurations that this camera device supports 13916 (i.e. format, width, height, output/input stream). 13917 </description> 13918 <details> 13919 These are output stream configurations for use with 13920 dataSpace DYNAMIC_DEPTH. The configurations are 13921 listed as `(format, width, height, input?)` tuples. 13922 13923 Only devices that support depth output for at least 13924 the HAL_PIXEL_FORMAT_Y16 dense depth map along with 13925 HAL_PIXEL_FORMAT_BLOB with the same size or size with 13926 the same aspect ratio can have dynamic depth dataspace 13927 stream configuration. android.depth.depthIsExclusive also 13928 needs to be set to FALSE. 13929 </details> 13930 <hal_details> 13931 Do not set this property directly. 13932 It is populated by camera framework and must not be set 13933 at the HAL layer. 13934 </hal_details> 13935 <tag id="DEPTH" /> 13936 </entry> 13937 <entry name="availableDynamicDepthMinFrameDurations" type="int64" visibility="ndk_public" 13938 container="array" typedef="streamConfigurationDuration" hal_version="3.4"> 13939 <array> 13940 <size>4</size> 13941 <size>n</size> 13942 </array> 13943 <description>This lists the minimum frame duration for each 13944 format/size combination for dynamic depth output streams. 13945 </description> 13946 <units>(format, width, height, ns) x n</units> 13947 <details> 13948 This should correspond to the frame duration when only that 13949 stream is active, with all processing (typically in android.*.mode) 13950 set to either OFF or FAST. 13951 13952 When multiple streams are used in a request, the minimum frame 13953 duration will be max(individual stream min durations). 13954 13955 The minimum frame duration of a stream (of a particular format, size) 13956 is the same regardless of whether the stream is input or output. 13957 </details> 13958 <hal_details> 13959 Do not set this property directly. 13960 It is populated by camera framework and must not be set 13961 at the HAL layer. 13962 </hal_details> 13963 <tag id="DEPTH" /> 13964 </entry> 13965 <entry name="availableDynamicDepthStallDurations" type="int64" visibility="ndk_public" 13966 container="array" typedef="streamConfigurationDuration" hal_version="3.4"> 13967 <array> 13968 <size>4</size> 13969 <size>n</size> 13970 </array> 13971 <description>This lists the maximum stall duration for each 13972 output format/size combination for dynamic depth streams. 13973 </description> 13974 <units>(format, width, height, ns) x n</units> 13975 <details> 13976 A stall duration is how much extra time would get added 13977 to the normal minimum frame duration for a repeating request 13978 that has streams with non-zero stall. 13979 13980 All dynamic depth output streams may have a nonzero stall 13981 duration. 13982 </details> 13983 <hal_details> 13984 Do not set this property directly. 13985 It is populated by camera framework and must not be set 13986 at the HAL layer. 13987 </hal_details> 13988 <tag id="DEPTH" /> 13989 </entry> 13990 <entry name="availableDepthStreamConfigurationsMaximumResolution" type="int32" 13991 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 13992 hal_version="3.6"> 13993 <array> 13994 <size>n</size> 13995 <size>4</size> 13996 </array> 13997 <enum> 13998 <value>OUTPUT</value> 13999 <value>INPUT</value> 14000 </enum> 14001 <description>The available depth dataspace stream 14002 configurations that this camera device supports 14003 (i.e. format, width, height, output/input stream) when a CaptureRequest is submitted with 14004 android.sensor.pixelMode set to 14005 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14006 </description> 14007 <details> 14008 Analogous to android.depth.availableDepthStreamConfigurations, for configurations which 14009 are applicable when android.sensor.pixelMode is set to 14010 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14011 </details> 14012 <tag id="DEPTH" /> 14013 </entry> 14014 <entry name="availableDepthMinFrameDurationsMaximumResolution" type="int64" 14015 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14016 hal_version="3.6"> 14017 <array> 14018 <size>4</size> 14019 <size>n</size> 14020 </array> 14021 <description>This lists the minimum frame duration for each 14022 format/size combination for depth output formats when a CaptureRequest is submitted with 14023 android.sensor.pixelMode set to 14024 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14025 </description> 14026 <units>(format, width, height, ns) x n</units> 14027 <details> 14028 Analogous to android.depth.availableDepthMinFrameDurations, for configurations which 14029 are applicable when android.sensor.pixelMode is set to 14030 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14031 14032 See android.sensor.frameDuration and 14033 android.scaler.availableStallDurationsMaximumResolution for more details about 14034 calculating the max frame rate. 14035 </details> 14036 <tag id="DEPTH" /> 14037 </entry> 14038 <entry name="availableDepthStallDurationsMaximumResolution" type="int64" 14039 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14040 hal_version="3.6"> 14041 <array> 14042 <size>4</size> 14043 <size>n</size> 14044 </array> 14045 <description>This lists the maximum stall duration for each 14046 output format/size combination for depth streams for CaptureRequests where 14047 android.sensor.pixelMode is set to 14048 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14049 </description> 14050 <units>(format, width, height, ns) x n</units> 14051 <details> 14052 Analogous to android.depth.availableDepthStallDurations, for configurations which 14053 are applicable when android.sensor.pixelMode is set to 14054 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14055 </details> 14056 <tag id="DEPTH" /> 14057 </entry> 14058 <entry name="availableDynamicDepthStreamConfigurationsMaximumResolution" type="int32" 14059 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 14060 hal_version="3.6"> 14061 <array> 14062 <size>n</size> 14063 <size>4</size> 14064 </array> 14065 <enum> 14066 <value>OUTPUT</value> 14067 <value>INPUT</value> 14068 </enum> 14069 <description>The available dynamic depth dataspace stream 14070 configurations that this camera device supports (i.e. format, width, height, 14071 output/input stream) for CaptureRequests where android.sensor.pixelMode is set to 14072 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14073 </description> 14074 <details> 14075 Analogous to android.depth.availableDynamicDepthStreamConfigurations, for configurations 14076 which are applicable when android.sensor.pixelMode is set to 14077 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14078 </details> 14079 <hal_details> 14080 Do not set this property directly. 14081 It is populated by camera framework and must not be set 14082 at the HAL layer. 14083 </hal_details> 14084 <tag id="DEPTH" /> 14085 </entry> 14086 <entry name="availableDynamicDepthMinFrameDurationsMaximumResolution" type="int64" 14087 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14088 hal_version="3.6"> 14089 <array> 14090 <size>4</size> 14091 <size>n</size> 14092 </array> 14093 <description>This lists the minimum frame duration for each 14094 format/size combination for dynamic depth output streams for CaptureRequests where 14095 android.sensor.pixelMode is set to 14096 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14097 </description> 14098 <units>(format, width, height, ns) x n</units> 14099 <details> 14100 Analogous to android.depth.availableDynamicDepthMinFrameDurations, for configurations 14101 which are applicable when android.sensor.pixelMode is set to 14102 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14103 </details> 14104 <hal_details> 14105 Do not set this property directly. 14106 It is populated by camera framework and must not be set 14107 at the HAL layer. 14108 </hal_details> 14109 <tag id="DEPTH" /> 14110 </entry> 14111 <entry name="availableDynamicDepthStallDurationsMaximumResolution" type="int64" 14112 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14113 hal_version="3.6"> 14114 <array> 14115 <size>4</size> 14116 <size>n</size> 14117 </array> 14118 <description>This lists the maximum stall duration for each 14119 output format/size combination for dynamic depth streams for CaptureRequests where 14120 android.sensor.pixelMode is set to 14121 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14122 </description> 14123 <units>(format, width, height, ns) x n</units> 14124 <details> 14125 Analogous to android.depth.availableDynamicDepthStallDurations, for configurations 14126 which are applicable when android.sensor.pixelMode is set to 14127 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14128 </details> 14129 <hal_details> 14130 Do not set this property directly. 14131 It is populated by camera framework and must not be set 14132 at the HAL layer. 14133 </hal_details> 14134 <tag id="DEPTH" /> 14135 </entry> 14136 </static> 14137 </section> 14138 <section name="logicalMultiCamera"> 14139 <static> 14140 <entry name="physicalIds" type="byte" visibility="ndk_public" 14141 container="array" hwlevel="limited" hal_version="3.3"> 14142 <array> 14143 <size>n</size> 14144 </array> 14145 <description>String containing the ids of the underlying physical cameras. 14146 </description> 14147 <units>UTF-8 null-terminated string</units> 14148 <details> 14149 For a logical camera, this is concatenation of all underlying physical camera IDs. 14150 The null terminator for physical camera ID must be preserved so that the whole string 14151 can be tokenized using '\0' to generate list of physical camera IDs. 14152 14153 For example, if the physical camera IDs of the logical camera are "2" and "3", the 14154 value of this tag will be ['2', '\0', '3', '\0']. 14155 14156 The number of physical camera IDs must be no less than 2. 14157 </details> 14158 <hal_details> 14159 Each physical camera id should uniquely identify a camera lens in the system. 14160 So if each camera lens only backs one logical camera, all camera IDs in the system, 14161 physical IDs or non-physical IDs, should be unique. 14162 14163 In rare cases, one camera lens backs two different logical cameras, the 14164 physicalIds of both logical cameras should contain a physical camera ID 14165 identifying that same camera lens. For example, if the mobile device has 3 rear facing 14166 cameras and no front facing cameras, and the 3 rear facing lenses may be modelled as 14167 2 logical cameras: 14168 14169 - "[email protected]/internal/10": physicalIds: "camera0", "camera42" 14170 - "[email protected]/internal/11": physicalIds: "camera1", "camera42" 14171 14172 In this case, the two logical cameras are conflicting devices because they are backed 14173 by a common lens. 14174 14175 Physical camera IDs can be an arbitrary string not containing '\0'. 14176 </hal_details> 14177 <tag id="LOGICALCAMERA" /> 14178 </entry> 14179 <entry name="sensorSyncType" type="byte" visibility="public" 14180 enum="true" hwlevel="limited" hal_version="3.3"> 14181 <enum> 14182 <value>APPROXIMATE 14183 <notes> 14184 A software mechanism is used to synchronize between the physical cameras. As a result, 14185 the timestamp of an image from a physical stream is only an approximation of the 14186 image sensor start-of-exposure time. 14187 </notes> 14188 </value> 14189 <value>CALIBRATED 14190 <notes> 14191 The camera device supports frame timestamp synchronization at the hardware level, 14192 and the timestamp of a physical stream image accurately reflects its 14193 start-of-exposure time. 14194 </notes> 14195 </value> 14196 </enum> 14197 <description>The accuracy of frame timestamp synchronization between physical cameras</description> 14198 <details> 14199 The accuracy of the frame timestamp synchronization determines the physical cameras' 14200 ability to start exposure at the same time. If the sensorSyncType is CALIBRATED, the 14201 physical camera sensors usually run in leader/follower mode where one sensor generates a 14202 timing signal for the other, so that their shutter time is synchronized. For APPROXIMATE 14203 sensorSyncType, the camera sensors usually run in leader/leader mode, where both sensors 14204 use their own timing generator, and there could be offset between their start of exposure. 14205 14206 In both cases, all images generated for a particular capture request still carry the same 14207 timestamps, so that they can be used to look up the matching frame number and 14208 onCaptureStarted callback. 14209 14210 This tag is only applicable if the logical camera device supports concurrent physical 14211 streams from different physical cameras. 14212 </details> 14213 <tag id="LOGICALCAMERA" /> 14214 </entry> 14215 </static> 14216 <dynamic> 14217 <entry name="activePhysicalId" type="byte" visibility="public" 14218 typedef="string" hal_version="3.4"> 14219 <description>String containing the ID of the underlying active physical camera. 14220 </description> 14221 <units>UTF-8 null-terminated string</units> 14222 <details> 14223 The ID of the active physical camera that's backing the logical camera. All camera 14224 streams and metadata that are not physical camera specific will be originating from this 14225 physical camera. 14226 14227 For a logical camera made up of physical cameras where each camera's lenses have 14228 different characteristics, the camera device may choose to switch between the physical 14229 cameras when application changes FOCAL_LENGTH or SCALER_CROP_REGION. 14230 At the time of lens switch, this result metadata reflects the new active physical camera 14231 ID. 14232 14233 This key will be available if the camera device advertises this key via {@link 14234 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 14235 When available, this must be one of valid physical IDs backing this logical multi-camera. 14236 If this key is not available for a logical multi-camera, the camera device implementation 14237 may still switch between different active physical cameras based on use case, but the 14238 current active physical camera information won't be available to the application. 14239 </details> 14240 <hal_details> 14241 Staring from HIDL ICameraDevice version 3.5, the tag must be available in the capture 14242 result metadata to indicate current active physical camera ID. 14243 </hal_details> 14244 <tag id="LOGICALCAMERA" /> 14245 </entry> 14246 <entry name="activePhysicalSensorCropRegion" type="int32" visibility="public" 14247 container="array" typedef="rectangle" hal_version="3.10"> 14248 <array> 14249 <size>4</size> 14250 </array> 14251 <description>The current region of the active physical sensor that will be read out for this 14252 capture.</description> 14253 <units>Pixel coordinates relative to 14254 android.sensor.info.activeArraySize or 14255 android.sensor.info.preCorrectionActiveArraySize of the currently 14256 android.logicalMultiCamera.activePhysicalId depending on distortion correction capability 14257 and mode</units> 14258 <details> 14259 This capture result matches with android.scaler.cropRegion on non-logical single 14260 camera sensor devices. In case of logical cameras that can switch between several 14261 physical devices in response to android.control.zoomRatio, this capture result will 14262 not behave like android.scaler.cropRegion and android.control.zoomRatio, where the 14263 combination of both reflects the effective zoom and crop of the logical camera output. 14264 Instead, this capture result value will describe the zoom and crop of the active physical 14265 device. Some examples of when the value of this capture result will change include 14266 switches between different physical lenses, switches between regular and maximum 14267 resolution pixel mode and going through the device digital or optical range. 14268 This capture result is similar to android.scaler.cropRegion with respect to distortion 14269 correction. When the distortion correction mode is OFF, the coordinate system follows 14270 android.sensor.info.preCorrectionActiveArraySize, with (0, 0) being the top-left pixel 14271 of the pre-correction active array. When the distortion correction mode is not OFF, 14272 the coordinate system follows android.sensor.info.activeArraySize, with (0, 0) being 14273 the top-left pixel of the active array. 14274 14275 For camera devices with the 14276 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 14277 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 14278 lists android.sensor.pixelMode, 14279 the current active physical device 14280 android.sensor.info.activeArraySizeMaximumResolution / 14281 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 14282 coordinate system for requests where android.sensor.pixelMode is set to 14283 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14284 </details> 14285 <ndk_details> 14286 The data representation is int[4], which maps to (left, top, width, height). 14287 </ndk_details> 14288 <hal_details> 14289 The output streams must maintain square pixels at all 14290 times, no matter what the relative aspect ratios of the 14291 crop region and the stream are. Negative values for 14292 corner are allowed for raw output if full pixel array is 14293 larger than active pixel array. Width and height may be 14294 rounded to nearest larger supportable width, especially 14295 for raw output, where only a few fixed scales may be 14296 possible. 14297 </hal_details> 14298 <tag id="LOGICALCAMERA" /> 14299 </entry> 14300 </dynamic> 14301 </section> 14302 <section name="distortionCorrection"> 14303 <controls> 14304 <entry name="mode" type="byte" visibility="public" enum="true" hal_version="3.3"> 14305 <enum> 14306 <value>OFF 14307 <notes>No distortion correction is applied.</notes></value> 14308 <value>FAST <notes>Lens distortion correction is applied without reducing frame rate 14309 relative to sensor output. It may be the same as OFF if distortion correction would 14310 reduce frame rate relative to sensor.</notes></value> 14311 <value>HIGH_QUALITY <notes>High-quality distortion correction is applied, at the cost of 14312 possibly reduced frame rate relative to sensor output.</notes></value> 14313 </enum> 14314 <description>Mode of operation for the lens distortion correction block.</description> 14315 <range>android.distortionCorrection.availableModes</range> 14316 <details>The lens distortion correction block attempts to improve image quality by fixing 14317 radial, tangential, or other geometric aberrations in the camera device's optics. If 14318 available, the android.lens.distortion field documents the lens's distortion parameters. 14319 14320 OFF means no distortion correction is done. 14321 14322 FAST/HIGH_QUALITY both mean camera device determined distortion correction will be 14323 applied. HIGH_QUALITY mode indicates that the camera device will use the highest-quality 14324 correction algorithms, even if it slows down capture rate. FAST means the camera device 14325 will not slow down capture rate when applying correction. FAST may be the same as OFF if 14326 any correction at all would slow down capture rate. Every output stream will have a 14327 similar amount of enhancement applied. 14328 14329 The correction only applies to processed outputs such as YUV, Y8, JPEG, or DEPTH16; it is 14330 not applied to any RAW output. 14331 14332 This control will be on by default on devices that support this control. Applications 14333 disabling distortion correction need to pay extra attention with the coordinate system of 14334 metering regions, crop region, and face rectangles. When distortion correction is OFF, 14335 metadata coordinates follow the coordinate system of 14336 android.sensor.info.preCorrectionActiveArraySize. When distortion is not OFF, metadata 14337 coordinates follow the coordinate system of android.sensor.info.activeArraySize. The 14338 camera device will map these metadata fields to match the corrected image produced by the 14339 camera device, for both capture requests and results. However, this mapping is not very 14340 precise, since rectangles do not generally map to rectangles when corrected. Only linear 14341 scaling between the active array and precorrection active array coordinates is 14342 performed. Applications that require precise correction of metadata need to undo that 14343 linear scaling, and apply a more complete correction that takes into the account the app's 14344 own requirements. 14345 14346 The full list of metadata that is affected in this way by distortion correction is: 14347 14348 * android.control.afRegions 14349 * android.control.aeRegions 14350 * android.control.awbRegions 14351 * android.scaler.cropRegion 14352 * android.statistics.faces 14353 </details> 14354 </entry> 14355 </controls> 14356 <static> 14357 <entry name="availableModes" type="byte" visibility="public" 14358 type_notes="list of enums" container="array" typedef="enumList" hal_version="3.3"> 14359 <array> 14360 <size>n</size> 14361 </array> 14362 <description> 14363 List of distortion correction modes for android.distortionCorrection.mode that are 14364 supported by this camera device. 14365 </description> 14366 <range>Any value listed in android.distortionCorrection.mode</range> 14367 <details> 14368 No device is required to support this API; such devices will always list only 'OFF'. 14369 All devices that support this API will list both FAST and HIGH_QUALITY. 14370 </details> 14371 <hal_details> 14372 HAL must support both FAST and HIGH_QUALITY if distortion correction is available 14373 on the camera device, but the underlying implementation can be the same for both modes. 14374 That is, if the highest quality implementation on the camera device does not slow down 14375 capture rate, then FAST and HIGH_QUALITY will generate the same output. 14376 </hal_details> 14377 <tag id="V1" /> 14378 <tag id="REPROC" /> 14379 </entry> 14380 </static> 14381 <dynamic> 14382 <clone entry="android.distortionCorrection.mode" kind="controls" hal_version="3.3"> 14383 </clone> 14384 </dynamic> 14385 </section> 14386 <section name="heic"> 14387 <static> 14388 <namespace name="info"> 14389 <entry name="supported" type="byte" visibility="system" enum="true" 14390 typedef="boolean" hwlevel="limited" hal_version="3.4"> 14391 <enum> 14392 <value>FALSE</value> 14393 <value>TRUE</value> 14394 </enum> 14395 <description>Whether this camera device can support identical set of stream combinations 14396 involving HEIC image format, compared to the 14397 [table of combinations](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations) 14398 involving JPEG image format required for the device's hardware 14399 level and capabilities. 14400 </description> 14401 <details> 14402 All the static, control and dynamic metadata tags related to JPEG apply to HEIC formats 14403 as well. For example, the same android.jpeg.orientation and android.jpeg.quality are 14404 used to control the orientation and quality of the HEIC image. Configuring JPEG and 14405 HEIC streams at the same time is not supported. 14406 14407 If a camera device supports HEIC format (ISO/IEC 23008-12), not only does it 14408 support the existing mandatory stream 14409 [combinations](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations) 14410 required for the device's hardware level and capabilities, it also 14411 supports swapping each JPEG stream with HEIC stream in all guaranteed combinations. 14412 14413 For every HEIC stream configured by the application, the camera framework sets up 2 14414 internal streams with camera HAL: 14415 14416 * A YUV_420_888 or IMPLEMENTATION_DEFINED HAL stream as input to HEIC or HEVC encoder. 14417 * A BLOB stream with JPEG_APPS_SEGMENTS dataspace to extract application markers 14418 including EXIF and thumbnail to be saved in HEIF container. 14419 14420 A camera device can output HEIC format to the application if and only if: 14421 14422 * The system contains a HEIC or HEVC encoder with constant quality mode, and 14423 * This tag is set to TRUE, meaning that camera HAL supports replacing JPEG streams in 14424 all mandatory stream combinations with a [YUV_420_888/IMPLEMENTATION_DEFINED stream + 14425 JPEG_APPS_SEGMENT BLOB stream] combo. 14426 14427 As an example, if the camera device's hardware level is LIMITED, and it supports HEIC, 14428 in addition to the required stream combinations, HAL must support below stream 14429 combinations as well: 14430 14431 * IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + JPEG_SEGMENTS_BLOB, 14432 * PRIV PREVIEW + IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + JPEG_SEGMENTS_BLOB, 14433 * YUV PREVIEW + IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + JPEG_SEGMENTS_BLOB, 14434 * PRIV PREVIEW + YUV PREVIEW + IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + 14435 JPEG_SEGMENTS_BLOB 14436 14437 The selection logic between YUV_420_888 and IMPLEMENTATION_DEFINED for HAL internal 14438 stream is as follows: 14439 14440 if (HEIC encoder exists and supports the size) { 14441 use IMPLEMENTATION_DEFINED with GRALLOC_USAGE_HW_IMAGE_ENCODER usage flag; 14442 } else { 14443 // HVC encoder exists 14444 if (size is less than framework predefined tile size) { 14445 use IMPLEMENTATINO_DEFINED with GRALLOC_USAGE_HW_VIDEO_ENCODER usage flag; 14446 } else { 14447 use YUV_420_888; 14448 } 14449 } 14450 </details> 14451 <tag id="HEIC" /> 14452 </entry> 14453 <entry name="maxJpegAppSegmentsCount" type="byte" visibility="system" 14454 hwlevel="limited" hal_version="3.4"> 14455 <description>The maximum number of Jpeg APP segments supported by the camera HAL device. 14456 </description> 14457 <details> 14458 The camera framework will use this value to derive the size of the BLOB buffer with 14459 JPEG_APP_SEGMENTS dataspace, with each APP segment occupying at most 64K bytes. If the 14460 value of this tag is n, the size of the framework allocated buffer will be: 14461 14462 n * (2 + 0xFFFF) + sizeof(struct CameraBlob) 14463 14464 where 2 is number of bytes for APP marker, 0xFFFF is the maximum size per APP segment 14465 (including segment size). 14466 14467 The value of this tag must be at least 1, and APP1 marker (0xFFE1) segment must be the 14468 first segment stored in the JPEG_APPS_SEGMENTS BLOB buffer. APP1 segment stores EXIF and 14469 thumbnail. 14470 14471 Since media encoder embeds the orientation in the metadata of the output image, to be 14472 consistent between main image and thumbnail, camera HAL must not rotate the thumbnail 14473 image data based on android.jpeg.orientation. The framework will write the orientation 14474 into EXIF and HEIC container. 14475 14476 APP1 segment is followed immediately by one or multiple APP2 segments, and APPn 14477 segments. After the HAL fills and returns the JPEG_APP_SEGMENTS buffer, the camera 14478 framework modifies the APP1 segment by filling in the EXIF tags that are related to 14479 main image bitstream and the tags that can be derived from capture result metadata, 14480 before saving them into the HEIC container. 14481 14482 The value of this tag must not be more than 16. 14483 </details> 14484 <tag id="HEIC" /> 14485 </entry> 14486 </namespace> 14487 14488 <entry name="availableHeicStreamConfigurations" type="int32" visibility="ndk_public" 14489 enum="true" container="array" typedef="streamConfiguration" 14490 hwlevel="limited" hal_version="3.4"> 14491 <array> 14492 <size>n</size> 14493 <size>4</size> 14494 </array> 14495 <enum> 14496 <value>OUTPUT</value> 14497 <value>INPUT</value> 14498 </enum> 14499 <description>The available HEIC (ISO/IEC 23008-12) stream 14500 configurations that this camera device supports 14501 (i.e. format, width, height, output/input stream). 14502 </description> 14503 <details> 14504 The configurations are listed as `(format, width, height, input?)` tuples. 14505 14506 If the camera device supports HEIC image format, it will support identical set of stream 14507 combinations involving HEIC image format, compared to the combinations involving JPEG 14508 image format as required by the device's hardware level and capabilities. 14509 14510 All the static, control, and dynamic metadata tags related to JPEG apply to HEIC formats. 14511 Configuring JPEG and HEIC streams at the same time is not supported. 14512 </details> 14513 <ndk_details> 14514 All the configuration tuples `(format, width, height, input?)` will contain 14515 AIMAGE_FORMAT_HEIC format as OUTPUT only. 14516 </ndk_details> 14517 <hal_details> 14518 These are output stream configurations for use with dataSpace HAL_DATASPACE_HEIF. 14519 14520 Do not set this property directly. It is populated by camera framework and must not be 14521 set by the HAL layer. 14522 </hal_details> 14523 <tag id="HEIC" /> 14524 </entry> 14525 <entry name="availableHeicMinFrameDurations" type="int64" visibility="ndk_public" 14526 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 14527 hal_version="3.4"> 14528 <array> 14529 <size>4</size> 14530 <size>n</size> 14531 </array> 14532 <description>This lists the minimum frame duration for each 14533 format/size combination for HEIC output formats. 14534 </description> 14535 <units>(format, width, height, ns) x n</units> 14536 <details> 14537 This should correspond to the frame duration when only that 14538 stream is active, with all processing (typically in android.*.mode) 14539 set to either OFF or FAST. 14540 14541 When multiple streams are used in a request, the minimum frame 14542 duration will be max(individual stream min durations). 14543 14544 See android.sensor.frameDuration and 14545 android.scaler.availableStallDurations for more details about 14546 calculating the max frame rate. 14547 </details> 14548 <hal_details> 14549 Do not set this property directly. It is populated by camera framework and must not be 14550 set by the HAL layer. 14551 </hal_details> 14552 <tag id="HEIC" /> 14553 </entry> 14554 <entry name="availableHeicStallDurations" type="int64" visibility="ndk_public" 14555 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 14556 hal_version="3.4"> 14557 <array> 14558 <size>4</size> 14559 <size>n</size> 14560 </array> 14561 <description>This lists the maximum stall duration for each 14562 output format/size combination for HEIC streams. 14563 </description> 14564 <units>(format, width, height, ns) x n</units> 14565 <details> 14566 A stall duration is how much extra time would get added 14567 to the normal minimum frame duration for a repeating request 14568 that has streams with non-zero stall. 14569 14570 This functions similarly to 14571 android.scaler.availableStallDurations for HEIC 14572 streams. 14573 14574 All HEIC output stream formats may have a nonzero stall 14575 duration. 14576 </details> 14577 <hal_details> 14578 Do not set this property directly. It is populated by camera framework and must not be 14579 set by the HAL layer. 14580 </hal_details> 14581 <tag id="HEIC" /> 14582 </entry> 14583 <entry name="availableHeicStreamConfigurationsMaximumResolution" type="int32" 14584 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 14585 hal_version="3.6"> 14586 <array> 14587 <size>n</size> 14588 <size>4</size> 14589 </array> 14590 <enum> 14591 <value>OUTPUT</value> 14592 <value>INPUT</value> 14593 </enum> 14594 <description>The available HEIC (ISO/IEC 23008-12) stream 14595 configurations that this camera device supports 14596 (i.e. format, width, height, output/input stream). 14597 </description> 14598 <details> 14599 Refer to android.heic.availableHeicStreamConfigurations for details. 14600 </details> 14601 <ndk_details> 14602 All the configuration tuples `(format, width, height, input?)` will contain 14603 AIMAGE_FORMAT_HEIC format as OUTPUT only. 14604 </ndk_details> 14605 <hal_details> 14606 These are output stream configurations for use with dataSpace HAL_DATASPACE_HEIF. 14607 14608 Do not set this property directly. It is populated by camera framework and must not be 14609 set by the HAL layer. 14610 </hal_details> 14611 <tag id="HEIC" /> 14612 </entry> 14613 <entry name="availableHeicMinFrameDurationsMaximumResolution" type="int64" 14614 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14615 hal_version="3.6"> 14616 <array> 14617 <size>4</size> 14618 <size>n</size> 14619 </array> 14620 <description>This lists the minimum frame duration for each 14621 format/size combination for HEIC output formats for CaptureRequests where 14622 android.sensor.pixelMode is set to 14623 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14624 </description> 14625 <units>(format, width, height, ns) x n</units> 14626 <details> 14627 Refer to android.heic.availableHeicMinFrameDurations for details. 14628 </details> 14629 <hal_details> 14630 Do not set this property directly. It is populated by camera framework and must not be 14631 set by the HAL layer. 14632 </hal_details> 14633 <tag id="HEIC" /> 14634 </entry> 14635 <entry name="availableHeicStallDurationsMaximumResolution" type="int64" 14636 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14637 hal_version="3.6"> 14638 <array> 14639 <size>4</size> 14640 <size>n</size> 14641 </array> 14642 <description>This lists the maximum stall duration for each 14643 output format/size combination for HEIC streams for CaptureRequests where 14644 android.sensor.pixelMode is set to 14645 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14646 </description> 14647 <units>(format, width, height, ns) x n</units> 14648 <details> 14649 Refer to android.heic.availableHeicStallDurations for details. 14650 </details> 14651 <hal_details> 14652 Do not set this property directly. It is populated by camera framework and must not be 14653 set by the HAL layer. 14654 </hal_details> 14655 <tag id="HEIC" /> 14656 </entry> 14657 <entry name="availableHeicUltraHdrStreamConfigurations" type="int32" visibility="ndk_public" 14658 enum="true" container="array" typedef="streamConfiguration" hwlevel="limited" 14659 aconfig_flag="camera_heif_gainmap" hal_version="3.11"> 14660 <array> 14661 <size>n</size> 14662 <size>4</size> 14663 </array> 14664 <enum> 14665 <value>OUTPUT</value> 14666 <value>INPUT</value> 14667 </enum> 14668 <description>The available HEIC (ISO/IEC 23008-12/24) UltraHDR stream 14669 configurations that this camera device supports 14670 (i.e. format, width, height, output/input stream). 14671 </description> 14672 <details> 14673 The configurations are listed as `(format, width, height, input?)` tuples. 14674 14675 All the static, control, and dynamic metadata tags related to JPEG apply to HEIC formats. 14676 Configuring JPEG and HEIC streams at the same time is not supported. 14677 </details> 14678 <ndk_details> 14679 All the configuration tuples `(format, width, height, input?)` will contain 14680 AIMAGE_FORMAT_HEIC format as OUTPUT only. 14681 </ndk_details> 14682 <hal_details> 14683 These are output stream configurations for use with dataSpace DATASPACE_HEIF_ULTRAHDR. 14684 </hal_details> 14685 <tag id="HEIC" /> 14686 </entry> 14687 <entry name="availableHeicUltraHdrMinFrameDurations" type="int64" visibility="ndk_public" 14688 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 14689 aconfig_flag="camera_heif_gainmap" hal_version="3.11"> 14690 <array> 14691 <size>4</size> 14692 <size>n</size> 14693 </array> 14694 <description>This lists the minimum frame duration for each 14695 format/size combination for HEIC UltraHDR output formats. 14696 </description> 14697 <units>(format, width, height, ns) x n</units> 14698 <details> 14699 This should correspond to the frame duration when only that 14700 stream is active, with all processing (typically in android.*.mode) 14701 set to either OFF or FAST. 14702 14703 When multiple streams are used in a request, the minimum frame 14704 duration will be max(individual stream min durations). 14705 14706 See android.sensor.frameDuration and 14707 android.scaler.availableStallDurations for more details about 14708 calculating the max frame rate. 14709 </details> 14710 <tag id="HEIC" /> 14711 </entry> 14712 <entry name="availableHeicUltraHdrStallDurations" type="int64" visibility="ndk_public" 14713 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 14714 aconfig_flag="camera_heif_gainmap" hal_version="3.11"> 14715 <array> 14716 <size>4</size> 14717 <size>n</size> 14718 </array> 14719 <description>This lists the maximum stall duration for each 14720 output format/size combination for HEIC UltraHDR streams. 14721 </description> 14722 <units>(format, width, height, ns) x n</units> 14723 <details> 14724 A stall duration is how much extra time would get added 14725 to the normal minimum frame duration for a repeating request 14726 that has streams with non-zero stall. 14727 14728 This functions similarly to 14729 android.scaler.availableStallDurations for HEIC UltraHDR 14730 streams. 14731 14732 All HEIC output stream formats may have a nonzero stall 14733 duration. 14734 </details> 14735 <tag id="HEIC" /> 14736 </entry> 14737 <entry name="availableHeicUltraHdrStreamConfigurationsMaximumResolution" type="int32" 14738 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 14739 aconfig_flag="camera_heif_gainmap" hal_version="3.11"> 14740 <array> 14741 <size>n</size> 14742 <size>4</size> 14743 </array> 14744 <enum> 14745 <value>OUTPUT</value> 14746 <value>INPUT</value> 14747 </enum> 14748 <description>The available HEIC (ISO/IEC 23008-12/24) UltraHDR stream 14749 configurations that this camera device supports 14750 (i.e. format, width, height, output/input stream) for CaptureRequests where 14751 android.sensor.pixelMode is set to 14752 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14753 </description> 14754 <details> 14755 Refer to android.heic.availableHeicStreamConfigurations for details. 14756 </details> 14757 <ndk_details> 14758 All the configuration tuples `(format, width, height, input?)` will contain 14759 AIMAGE_FORMAT_HEIC format as OUTPUT only. 14760 </ndk_details> 14761 <hal_details> 14762 These are output stream configurations for use with dataSpace DATASPACE_HEIF_ULTRAHDR. 14763 </hal_details> 14764 <tag id="HEIC" /> 14765 </entry> 14766 <entry name="availableHeicUltraHdrMinFrameDurationsMaximumResolution" type="int64" 14767 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14768 aconfig_flag="camera_heif_gainmap" hal_version="3.11"> 14769 <array> 14770 <size>4</size> 14771 <size>n</size> 14772 </array> 14773 <description>This lists the minimum frame duration for each 14774 format/size combination for HEIC UltraHDR output formats for CaptureRequests where 14775 android.sensor.pixelMode is set to 14776 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14777 </description> 14778 <units>(format, width, height, ns) x n</units> 14779 <details> 14780 Refer to android.heic.availableHeicMinFrameDurations for details. 14781 </details> 14782 <tag id="HEIC" /> 14783 </entry> 14784 <entry name="availableHeicUltraHdrStallDurationsMaximumResolution" type="int64" 14785 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14786 aconfig_flag="camera_heif_gainmap" hal_version="3.11"> 14787 <array> 14788 <size>4</size> 14789 <size>n</size> 14790 </array> 14791 <description>This lists the maximum stall duration for each 14792 output format/size combination for HEIC UltraHDR streams for CaptureRequests where 14793 android.sensor.pixelMode is set to 14794 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14795 </description> 14796 <units>(format, width, height, ns) x n</units> 14797 <details> 14798 Refer to android.heic.availableHeicStallDurations for details. 14799 </details> 14800 <tag id="HEIC" /> 14801 </entry> 14802 </static> 14803 </section> 14804 <section name="automotive"> 14805 <static> 14806 <namespace name="lens"> 14807 <entry name="facing" type="byte" visibility="public" enum="true" container="array" 14808 hal_version="3.8"> 14809 <array> 14810 <size>n</size> 14811 </array> 14812 <enum> 14813 <value>EXTERIOR_OTHER 14814 <notes> 14815 The camera device faces the outside of the vehicle body frame but not exactly 14816 one of the exterior sides defined by this enum. Applications should determine 14817 the exact facing direction from android.lens.poseRotation and 14818 android.lens.poseTranslation. 14819 </notes> 14820 </value> 14821 <value>EXTERIOR_FRONT 14822 <notes> 14823 The camera device faces the front of the vehicle body frame. 14824 </notes> 14825 </value> 14826 <value>EXTERIOR_REAR 14827 <notes> 14828 The camera device faces the rear of the vehicle body frame. 14829 </notes> 14830 </value> 14831 <value>EXTERIOR_LEFT 14832 <notes> 14833 The camera device faces the left side of the vehicle body frame. 14834 </notes> 14835 </value> 14836 <value>EXTERIOR_RIGHT 14837 <notes> 14838 The camera device faces the right side of the vehicle body frame. 14839 </notes> 14840 </value> 14841 <value>INTERIOR_OTHER 14842 <notes> 14843 The camera device faces the inside of the vehicle body frame but not exactly 14844 one of seats described by this enum. Applications should determine the exact 14845 facing direction from android.lens.poseRotation and android.lens.poseTranslation. 14846 </notes> 14847 </value> 14848 <value>INTERIOR_SEAT_ROW_1_LEFT 14849 <notes> 14850 The camera device faces the left side seat of the first row. 14851 </notes> 14852 </value> 14853 <value>INTERIOR_SEAT_ROW_1_CENTER 14854 <notes> 14855 The camera device faces the center seat of the first row. 14856 </notes> 14857 </value> 14858 <value>INTERIOR_SEAT_ROW_1_RIGHT 14859 <notes> 14860 The camera device faces the right seat of the first row. 14861 </notes> 14862 </value> 14863 <value>INTERIOR_SEAT_ROW_2_LEFT 14864 <notes> 14865 The camera device faces the left side seat of the second row. 14866 </notes> 14867 </value> 14868 <value>INTERIOR_SEAT_ROW_2_CENTER 14869 <notes> 14870 The camera device faces the center seat of the second row. 14871 </notes> 14872 </value> 14873 <value>INTERIOR_SEAT_ROW_2_RIGHT 14874 <notes> 14875 The camera device faces the right side seat of the second row. 14876 </notes> 14877 </value> 14878 <value>INTERIOR_SEAT_ROW_3_LEFT 14879 <notes> 14880 The camera device faces the left side seat of the third row. 14881 </notes> 14882 </value> 14883 <value>INTERIOR_SEAT_ROW_3_CENTER 14884 <notes> 14885 The camera device faces the center seat of the third row. 14886 </notes> 14887 </value> 14888 <value>INTERIOR_SEAT_ROW_3_RIGHT 14889 <notes> 14890 The camera device faces the right seat of the third row. 14891 </notes> 14892 </value> 14893 </enum> 14894 <description> 14895 The direction of the camera faces relative to the vehicle body frame and the 14896 passenger seats. 14897 </description> 14898 <details> 14899 This enum defines the lens facing characteristic of the cameras on the automotive 14900 devices with locations android.automotive.location defines. If the system has 14901 FEATURE_AUTOMOTIVE, the camera will have this entry in its static metadata. 14902 14903 When android.automotive.location is INTERIOR, this has one or more INTERIOR_\* 14904 values or a single EXTERIOR_\* value. When this has more than one INTERIOR_\*, 14905 the first value must be the one for the seat closest to the optical axis. If this 14906 contains INTERIOR_OTHER, all other values will be ineffective. 14907 14908 When android.automotive.location is EXTERIOR_\* or EXTRA, this has a single 14909 EXTERIOR_\* value. 14910 14911 If a camera has INTERIOR_OTHER or EXTERIOR_OTHER, or more than one camera is at the 14912 same location and facing the same direction, their static metadata will list the 14913 following entries, so that applications can determine their lenses' exact facing 14914 directions: 14915 14916 * android.lens.poseReference 14917 * android.lens.poseRotation 14918 * android.lens.poseTranslation 14919 </details> 14920 </entry> 14921 </namespace> 14922 <entry name="location" type="byte" visibility="public" enum="true" hal_version="3.8"> 14923 <enum> 14924 <value>INTERIOR 14925 <notes> 14926 The camera device exists inside of the vehicle cabin. 14927 </notes> 14928 </value> 14929 <value>EXTERIOR_OTHER 14930 <notes> 14931 The camera exists outside of the vehicle body frame but not exactly on one of the 14932 exterior locations this enum defines. The applications should determine the exact 14933 location from android.lens.poseTranslation. 14934 </notes> 14935 </value> 14936 <value>EXTERIOR_FRONT 14937 <notes> 14938 The camera device exists outside of the vehicle body frame and on its front side. 14939 </notes> 14940 </value> 14941 <value>EXTERIOR_REAR 14942 <notes> 14943 The camera device exists outside of the vehicle body frame and on its rear side. 14944 </notes> 14945 </value> 14946 <value>EXTERIOR_LEFT 14947 <notes> 14948 The camera device exists outside and on left side of the vehicle body frame. 14949 </notes> 14950 </value> 14951 <value>EXTERIOR_RIGHT 14952 <notes> 14953 The camera device exists outside and on right side of the vehicle body frame. 14954 </notes> 14955 </value> 14956 <value>EXTRA_OTHER 14957 <notes> 14958 The camera device exists on an extra vehicle, such as the trailer, but not exactly 14959 on one of front, rear, left, or right side. Applications should determine the exact 14960 location from android.lens.poseTranslation. 14961 </notes> 14962 </value> 14963 <value>EXTRA_FRONT 14964 <notes> 14965 The camera device exists outside of the extra vehicle's body frame and on its front 14966 side. 14967 </notes> 14968 </value> 14969 <value>EXTRA_REAR 14970 <notes> 14971 The camera device exists outside of the extra vehicle's body frame and on its rear 14972 side. 14973 </notes> 14974 </value> 14975 <value>EXTRA_LEFT 14976 <notes> 14977 The camera device exists outside and on left side of the extra vehicle body. 14978 </notes> 14979 </value> 14980 <value>EXTRA_RIGHT 14981 <notes> 14982 The camera device exists outside and on right side of the extra vehicle body. 14983 </notes> 14984 </value> 14985 </enum> 14986 <description> 14987 Location of the cameras on the automotive devices. 14988 </description> 14989 <details> 14990 This enum defines the locations of the cameras relative to the vehicle body frame on 14991 [the automotive sensor coordinate system](https://source.android.com/devices/sensors/sensor-types#auto_axes). 14992 If the system has FEATURE_AUTOMOTIVE, the camera will have this entry in its static 14993 metadata. 14994 14995 * INTERIOR is the inside of the vehicle body frame (or the passenger cabin). 14996 * EXTERIOR is the outside of the vehicle body frame. 14997 * EXTRA is the extra vehicle such as a trailer. 14998 14999 Each side of the vehicle body frame on this coordinate system is defined as below: 15000 15001 * FRONT is where the Y-axis increases toward. 15002 * REAR is where the Y-axis decreases toward. 15003 * LEFT is where the X-axis decreases toward. 15004 * RIGHT is where the X-axis increases toward. 15005 15006 If the camera has either EXTERIOR_OTHER or EXTRA_OTHER, its static metadata will list 15007 the following entries, so that applications can determine the camera's exact location: 15008 15009 * android.lens.poseReference 15010 * android.lens.poseRotation 15011 * android.lens.poseTranslation 15012 </details> 15013 </entry> 15014 </static> 15015 </section> 15016 <section name="extension"> 15017 <controls> 15018 <entry name="strength" type="int32" visibility="fwk_java_public" hal_version="3.9"> 15019 <description>Strength of the extension post-processing effect 15020 </description> 15021 <range>0 - 100</range> 15022 <details> 15023 This control allows Camera extension clients to configure the strength of the applied 15024 extension effect. Strength equal to 0 means that the extension must not apply any 15025 post-processing and return a regular captured frame. Strength equal to 100 is the 15026 maximum level of post-processing. Values between 0 and 100 will have different effect 15027 depending on the extension type as described below: 15028 15029 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH BOKEH} - 15030 the strength is expected to control the amount of blur. 15031 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR HDR} and 15032 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT NIGHT} - 15033 the strength can control the amount of images fused and the brightness of the final image. 15034 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH FACE_RETOUCH} - 15035 the strength value will control the amount of cosmetic enhancement and skin 15036 smoothing. 15037 15038 The control will be supported if the capture request key is part of the list generated by 15039 {@link android.hardware.camera2.CameraExtensionCharacteristics#getAvailableCaptureRequestKeys}. 15040 The control is only defined and available to clients sending capture requests via 15041 {@link android.hardware.camera2.CameraExtensionSession}. 15042 If the client doesn't specify the extension strength value, then a default value will 15043 be set by the extension. Clients can retrieve the default value by checking the 15044 corresponding capture result. 15045 </details> 15046 </entry> 15047 </controls> 15048 <dynamic> 15049 <entry name="currentType" type="int32" visibility="fwk_java_public" hal_version="3.9"> 15050 <description>Contains the extension type of the currently active extension 15051 </description> 15052 <range>Extension type value listed in 15053 {@link android.hardware.camera2.CameraExtensionCharacteristics}</range> 15054 <details> 15055 The capture result will only be supported and included by camera extension 15056 {@link android.hardware.camera2.CameraExtensionSession sessions}. 15057 In case the extension session was configured to use 15058 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC AUTO}, 15059 then the extension type value will indicate the currently active extension like 15060 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR HDR}, 15061 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT NIGHT} etc. 15062 , and will never return 15063 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC AUTO}. 15064 In case the extension session was configured to use an extension different from 15065 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC AUTO}, 15066 then the result type will always match with the configured extension type. 15067 </details> 15068 </entry> 15069 <clone entry="android.extension.strength" kind="controls"> 15070 </clone> 15071 <entry name="nightModeIndicator" type="int32" visibility="public" optional="true" 15072 enum="true" aconfig_flag="night_mode_indicator" hal_version="3.11"> 15073 <enum> 15074 <value>UNKNOWN 15075 <notes> 15076 The camera can't accurately assess the scene's lighting to determine if a Night Mode 15077 Camera Extension capture would improve the photo. This can happen when the current 15078 camera configuration doesn't support night mode indicator detection, such as when 15079 the auto exposure mode is ON_AUTO_FLASH, ON_ALWAYS_FLASH, ON_AUTO_FLASH_REDEYE, or 15080 ON_EXTERNAL_FLASH. 15081 </notes> 15082 </value> 15083 <value>OFF 15084 <notes> 15085 The camera has detected lighting conditions that are sufficiently bright. Night 15086 Mode Camera Extensions is available but may not be able to optimize the camera 15087 settings to take a higher quality photo. 15088 </notes> 15089 </value> 15090 <value>ON 15091 <notes> 15092 The camera has detected low-light conditions. It is recommended to use Night Mode 15093 Camera Extension to optimize the camera settings to take a high-quality photo in 15094 the dark. 15095 </notes> 15096 </value> 15097 </enum> 15098 <description>Indicates when to activate Night Mode Camera Extension for high-quality 15099 still captures in low-light conditions.</description> 15100 <details> 15101 Provides awareness to the application when the current scene can benefit from using a 15102 Night Mode Camera Extension to take a high-quality photo. 15103 15104 Support for this capture result can be queried via 15105 {@link android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys}. 15106 15107 If the device supports this capability then it will also support 15108 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT NIGHT} 15109 and will be available in both 15110 {@link android.hardware.camera2.CameraCaptureSession sessions} and 15111 {@link android.hardware.camera2.CameraExtensionSession sessions}. 15112 15113 The value will be {@code UNKNOWN} in the following auto exposure modes: ON_AUTO_FLASH, 15114 ON_ALWAYS_FLASH, ON_AUTO_FLASH_REDEYE, or ON_EXTERNAL_FLASH. 15115 </details> 15116 </entry> 15117 </dynamic> 15118 </section> 15119 <section name="jpegr"> 15120 <static> 15121 <entry name="availableJpegRStreamConfigurations" type="int32" visibility="ndk_public" 15122 enum="true" container="array" typedef="streamConfiguration" 15123 hwlevel="limited" hal_version="3.9"> 15124 <array> 15125 <size>n</size> 15126 <size>4</size> 15127 </array> 15128 <enum> 15129 <value>OUTPUT</value> 15130 <value>INPUT</value> 15131 </enum> 15132 <description>The available Jpeg/R stream 15133 configurations that this camera device supports 15134 (i.e. format, width, height, output/input stream). 15135 </description> 15136 <details> 15137 The configurations are listed as `(format, width, height, input?)` tuples. 15138 15139 If the camera device supports Jpeg/R, it will support the same stream combinations with 15140 Jpeg/R as it does with P010. The stream combinations with Jpeg/R (or P010) supported 15141 by the device is determined by the device's hardware level and capabilities. 15142 15143 All the static, control, and dynamic metadata tags related to JPEG apply to Jpeg/R formats. 15144 Configuring JPEG and Jpeg/R streams at the same time is not supported. 15145 </details> 15146 <ndk_details> 15147 All the configuration tuples `(format, width, height, input?)` will contain 15148 AIMAGE_FORMAT_JPEGR format as OUTPUT only. 15149 </ndk_details> 15150 </entry> 15151 <entry name="availableJpegRMinFrameDurations" type="int64" visibility="ndk_public" 15152 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 15153 hal_version="3.9"> 15154 <array> 15155 <size>4</size> 15156 <size>n</size> 15157 </array> 15158 <description>This lists the minimum frame duration for each 15159 format/size combination for Jpeg/R output formats. 15160 </description> 15161 <units>(format, width, height, ns) x n</units> 15162 <details> 15163 This should correspond to the frame duration when only that 15164 stream is active, with all processing (typically in android.*.mode) 15165 set to either OFF or FAST. 15166 15167 When multiple streams are used in a request, the minimum frame 15168 duration will be max(individual stream min durations). 15169 15170 See android.sensor.frameDuration and 15171 android.scaler.availableStallDurations for more details about 15172 calculating the max frame rate. 15173 </details> 15174 </entry> 15175 <entry name="availableJpegRStallDurations" type="int64" visibility="ndk_public" 15176 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 15177 hal_version="3.9"> 15178 <array> 15179 <size>4</size> 15180 <size>n</size> 15181 </array> 15182 <description>This lists the maximum stall duration for each 15183 output format/size combination for Jpeg/R streams. 15184 </description> 15185 <units>(format, width, height, ns) x n</units> 15186 <details> 15187 A stall duration is how much extra time would get added 15188 to the normal minimum frame duration for a repeating request 15189 that has streams with non-zero stall. 15190 15191 This functions similarly to 15192 android.scaler.availableStallDurations for Jpeg/R 15193 streams. 15194 15195 All Jpeg/R output stream formats may have a nonzero stall 15196 duration. 15197 </details> 15198 </entry> 15199 <entry name="availableJpegRStreamConfigurationsMaximumResolution" type="int32" 15200 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 15201 hal_version="3.9"> 15202 <array> 15203 <size>n</size> 15204 <size>4</size> 15205 </array> 15206 <enum> 15207 <value>OUTPUT</value> 15208 <value>INPUT</value> 15209 </enum> 15210 <description>The available Jpeg/R stream 15211 configurations that this camera device supports 15212 (i.e. format, width, height, output/input stream). 15213 </description> 15214 <details> 15215 Refer to android.jpegr.availableJpegRStreamConfigurations for details. 15216 </details> 15217 <ndk_details> 15218 All the configuration tuples `(format, width, height, input?)` will contain 15219 AIMAGE_FORMAT_JPEG_R format as OUTPUT only. 15220 </ndk_details> 15221 </entry> 15222 <entry name="availableJpegRMinFrameDurationsMaximumResolution" type="int64" 15223 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 15224 hal_version="3.9"> 15225 <array> 15226 <size>4</size> 15227 <size>n</size> 15228 </array> 15229 <description>This lists the minimum frame duration for each 15230 format/size combination for Jpeg/R output formats for CaptureRequests where 15231 android.sensor.pixelMode is set to 15232 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 15233 </description> 15234 <units>(format, width, height, ns) x n</units> 15235 <details> 15236 Refer to android.jpegr.availableJpegRMinFrameDurations for details. 15237 </details> 15238 </entry> 15239 <entry name="availableJpegRStallDurationsMaximumResolution" type="int64" 15240 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 15241 hal_version="3.9"> 15242 <array> 15243 <size>4</size> 15244 <size>n</size> 15245 </array> 15246 <description>This lists the maximum stall duration for each 15247 output format/size combination for Jpeg/R streams for CaptureRequests where 15248 android.sensor.pixelMode is set to 15249 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 15250 </description> 15251 <units>(format, width, height, ns) x n</units> 15252 <details> 15253 Refer to android.jpegr.availableJpegRStallDurations for details. 15254 </details> 15255 </entry> 15256 </static> 15257 </section> 15258 <section name="sharedSession"> 15259 <static> 15260 <entry name="colorSpace" type="byte" visibility="fwk_only" optional="true" 15261 enum="true" aconfig_flag="camera_multi_client" hal_version="3.11"> 15262 <enum> 15263 <value id="-1">UNSPECIFIED</value> 15264 <value id="0">SRGB</value> 15265 <value id="7">DISPLAY_P3</value> 15266 <value id="16">BT2020_HLG</value> 15267 </enum> 15268 <description>Color space used for shared session configuration for all the output targets 15269 when camera is opened in shared mode. This should be one of the values specified in 15270 availableColorSpaceProfilesMap. 15271 </description> 15272 <hal_details> 15273 Do not set this property directly. Android camera framework will generate this tag if the 15274 camera device can be opened in shared mode. 15275 </hal_details> 15276 </entry> 15277 <entry name="outputConfigurations" type="int64" visibility="fwk_only" 15278 optional="true" container="array" aconfig_flag="camera_multi_client" 15279 hal_version="3.11"> 15280 <array> 15281 <size>n</size> 15282 </array> 15283 <description>List of shared output configurations that this camera device supports when 15284 camera is opened in shared mode. Array contains following entries for each supported 15285 shared configuration: 15286 1) surface type 15287 2) width 15288 3) height 15289 4) format 15290 5) mirrorMode 15291 6) useReadoutTimestamp 15292 7) timestampBase 15293 8) dataspace 15294 9) usage 15295 10) streamUsecase 15296 11) physical camera id len 15297 12) physical camera id as UTF-8 null terminated string. 15298 </description> 15299 <hal_details> 15300 Do not set this property directly. Android camera framework will generate this tag if the 15301 camera device can be opened in shared mode. 15302 </hal_details> 15303 </entry> 15304 <entry name="configuration" type="byte" visibility="fwk_system_public" 15305 synthetic="true" optional="true" typedef="sharedSessionConfiguration" 15306 aconfig_flag="camera_multi_client"> 15307 <description>The available stream configurations that this camera device supports for 15308 shared capture session when camera is opened in shared mode. Android camera framework 15309 will generate this tag if the camera device can be opened in shared mode. 15310 </description> 15311 <hal_details> 15312 Do not set this property directly (it is synthetic and will not be available at the 15313 HAL layer); 15314 </hal_details> 15315 </entry> 15316 </static> 15317 </section> 15318 <section name="desktopEffects"> 15319 <static> 15320 <entry name="capabilities" type="byte" visibility="system" optional="true" 15321 enum="true" type_notes="list of enums" container="array" typedef="enumList" 15322 aconfig_flag="desktop_effects"> 15323 <array> 15324 <size>n</size> 15325 </array> 15326 <enum> 15327 <value>BACKGROUND_BLUR 15328 <notes> 15329 Background blur can be activated via android.desktopEffects.backgroundBlurMode 15330 </notes> 15331 </value> 15332 <value>FACE_RETOUCH 15333 <notes> 15334 Face retouch can be activated via android.desktopEffects.faceRetouchMode 15335 </notes> 15336 </value> 15337 <value>PORTRAIT_RELIGHT 15338 <notes> 15339 Portrait relight can be activated via android.desktopEffects.portraitRelightMode 15340 </notes> 15341 </value> 15342 </enum> 15343 <description> 15344 List of special effects supported by the camera device. 15345 </description> 15346 <details> 15347 Available features supported by the camera device for large screen video conferencing. 15348 </details> 15349 </entry> 15350 <entry name="backgroundBlurModes" type="byte" visibility="system" optional="true" 15351 type_notes="list of enums (android.desktopEffects.backgroundBlurMode)" container="array" 15352 typedef="enumList" aconfig_flag="desktop_effects"> 15353 <array> 15354 <size>n</size> 15355 </array> 15356 <description> 15357 List of background blur modes supported by the camera device. The key will only exist 15358 if BACKGROUND_BLUR is listed by android.desktopEffects.capabilities. 15359 </description> 15360 <range>Any value listed in android.desktopEffects.backgroundBlurMode</range> 15361 <details> 15362 Lists the valid modes for android.desktopEffects.backgroundBlurMode. 15363 </details> 15364 </entry> 15365 </static> 15366 <controls> 15367 <entry name="backgroundBlurMode" type="byte" visibility="system" 15368 optional="true" enum="true" aconfig_flag="desktop_effects"> 15369 <enum> 15370 <value>OFF 15371 <notes> 15372 Don't use background blur 15373 </notes> 15374 </value> 15375 <value>LIGHT 15376 <notes> 15377 Blur the background with light blur strength 15378 </notes> 15379 </value> 15380 <value>FULL 15381 <notes> 15382 Blur the background with full blur strength 15383 </notes> 15384 </value> 15385 </enum> 15386 <description>Control how the background should be blurred. Supported modes are listed in 15387 android.desktopEffects.backgroundBlurModes by the camera device.</description> 15388 </entry> 15389 <entry name="faceRetouchMode" type="byte" visibility="system" 15390 optional="true" enum="true" typedef="boolean" aconfig_flag="desktop_effects"> 15391 <enum> 15392 <value>OFF 15393 <notes> 15394 Turn off face retouch 15395 </notes> 15396 </value> 15397 <value>ON 15398 <notes> 15399 Turn on face retouch. A strength can be set by android.desktopEffects.faceRetouchStrength 15400 </notes> 15401 </value> 15402 </enum> 15403 <description>Whether to enable face retouch effect.</description> 15404 </entry> 15405 <entry name="faceRetouchStrength" type="byte" visibility="system" 15406 optional="true" aconfig_flag="desktop_effects"> 15407 <description>Control the strength of face retouch applied to the frames. If 15408 android.desktopEffects.faceRetouchMode in ON without a faceRetouchStrength, 15409 a default will be set by the camera device.</description> 15410 <units>1-100; 100 is maximum strength.</units> 15411 </entry> 15412 <entry name="portraitRelightMode" type="byte" visibility="system" 15413 optional="true" enum="true" typedef="boolean" aconfig_flag="desktop_effects"> 15414 <enum> 15415 <value>OFF 15416 <notes> 15417 Do not use portrait relight 15418 </notes> 15419 </value> 15420 <value>ON 15421 <notes> 15422 Use portrait relight 15423 </notes> 15424 </value> 15425 </enum> 15426 <description>Whether to enable portrait relighting effect.</description> 15427 </entry> 15428 </controls> 15429 </section> 15430 </namespace> 15431</metadata> 15432
