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 </types> 171 172 <namespace name="android"> 173 <section name="colorCorrection"> 174 <controls> 175 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 176 <enum> 177 <value>TRANSFORM_MATRIX 178 <notes>Use the android.colorCorrection.transform matrix 179 and android.colorCorrection.gains to do color conversion. 180 181 All advanced white balance adjustments (not specified 182 by our white balance pipeline) must be disabled. 183 184 If AWB is enabled with `android.control.awbMode != OFF`, then 185 TRANSFORM_MATRIX is ignored. The camera device will override 186 this value to either FAST or HIGH_QUALITY. 187 </notes> 188 </value> 189 <value>FAST 190 <notes>Color correction processing must not slow down 191 capture rate relative to sensor raw output. 192 193 Advanced white balance adjustments above and beyond 194 the specified white balance pipeline may be applied. 195 196 If AWB is enabled with `android.control.awbMode != OFF`, then 197 the camera device uses the last frame's AWB values 198 (or defaults if AWB has never been run). 199 </notes> 200 </value> 201 <value>HIGH_QUALITY 202 <notes>Color correction processing operates at improved 203 quality but the capture rate might be reduced (relative to sensor 204 raw output rate) 205 206 Advanced white balance adjustments above and beyond 207 the specified white balance pipeline may be applied. 208 209 If AWB is enabled with `android.control.awbMode != OFF`, then 210 the camera device uses the last frame's AWB values 211 (or defaults if AWB has never been run). 212 </notes> 213 </value> 214 </enum> 215 216 <description> 217 The mode control selects how the image data is converted from the 218 sensor's native color into linear sRGB color. 219 </description> 220 <details> 221 When auto-white balance (AWB) is enabled with android.control.awbMode, this 222 control is overridden by the AWB routine. When AWB is disabled, the 223 application controls how the color mapping is performed. 224 225 We define the expected processing pipeline below. For consistency 226 across devices, this is always the case with TRANSFORM_MATRIX. 227 228 When either FAST or HIGH_QUALITY is used, the camera device may 229 do additional processing but android.colorCorrection.gains and 230 android.colorCorrection.transform will still be provided by the 231 camera device (in the results) and be roughly correct. 232 233 Switching to TRANSFORM_MATRIX and using the data provided from 234 FAST or HIGH_QUALITY will yield a picture with the same white point 235 as what was produced by the camera device in the earlier frame. 236 237 The expected processing pipeline is as follows: 238 239  240 241 The white balance is encoded by two values, a 4-channel white-balance 242 gain vector (applied in the Bayer domain), and a 3x3 color transform 243 matrix (applied after demosaic). 244 245 The 4-channel white-balance gains are defined as: 246 247 android.colorCorrection.gains = [ R G_even G_odd B ] 248 249 where `G_even` is the gain for green pixels on even rows of the 250 output, and `G_odd` is the gain for green pixels on the odd rows. 251 These may be identical for a given camera device implementation; if 252 the camera device does not support a separate gain for even/odd green 253 channels, it will use the `G_even` value, and write `G_odd` equal to 254 `G_even` in the output result metadata. 255 256 The matrices for color transforms are defined as a 9-entry vector: 257 258 android.colorCorrection.transform = [ I0 I1 I2 I3 I4 I5 I6 I7 I8 ] 259 260 which define a transform from input sensor colors, `P_in = [ r g b ]`, 261 to output linear sRGB, `P_out = [ r' g' b' ]`, 262 263 with colors as follows: 264 265 r' = I0r + I1g + I2b 266 g' = I3r + I4g + I5b 267 b' = I6r + I7g + I8b 268 269 Both the input and output value ranges must match. Overflow/underflow 270 values are clipped to fit within the range. 271 </details> 272 <hal_details> 273 HAL must support both FAST and HIGH_QUALITY if color correction control is available 274 on the camera device, but the underlying implementation can be the same for both modes. 275 That is, if the highest quality implementation on the camera device does not slow down 276 capture rate, then FAST and HIGH_QUALITY should generate the same output. 277 </hal_details> 278 </entry> 279 <entry name="transform" type="rational" visibility="public" 280 type_notes="3x3 rational matrix in row-major order" 281 container="array" typedef="colorSpaceTransform" hwlevel="full"> 282 <array> 283 <size>3</size> 284 <size>3</size> 285 </array> 286 <description>A color transform matrix to use to transform 287 from sensor RGB color space to output linear sRGB color space. 288 </description> 289 <units>Unitless scale factors</units> 290 <details>This matrix is either set by the camera device when the request 291 android.colorCorrection.mode is not TRANSFORM_MATRIX, or 292 directly by the application in the request when the 293 android.colorCorrection.mode is TRANSFORM_MATRIX. 294 295 In the latter case, the camera device may round the matrix to account 296 for precision issues; the final rounded matrix should be reported back 297 in this matrix result metadata. The transform should keep the magnitude 298 of the output color values within `[0, 1.0]` (assuming input color 299 values is within the normalized range `[0, 1.0]`), or clipping may occur. 300 301 The valid range of each matrix element varies on different devices, but 302 values within [-1.5, 3.0] are guaranteed not to be clipped. 303 </details> 304 </entry> 305 <entry name="gains" type="float" visibility="public" 306 type_notes="A 1D array of floats for 4 color channel gains" 307 container="array" typedef="rggbChannelVector" hwlevel="full"> 308 <array> 309 <size>4</size> 310 </array> 311 <description>Gains applying to Bayer raw color channels for 312 white-balance.</description> 313 <units>Unitless gain factors</units> 314 <details> 315 These per-channel gains are either set by the camera device 316 when the request android.colorCorrection.mode is not 317 TRANSFORM_MATRIX, or directly by the application in the 318 request when the android.colorCorrection.mode is 319 TRANSFORM_MATRIX. 320 321 The gains in the result metadata are the gains actually 322 applied by the camera device to the current frame. 323 324 The valid range of gains varies on different devices, but gains 325 between [1.0, 3.0] are guaranteed not to be clipped. Even if a given 326 device allows gains below 1.0, this is usually not recommended because 327 this can create color artifacts. 328 </details> 329 <hal_details> 330 The 4-channel white-balance gains are defined in 331 the order of `[R G_even G_odd B]`, where `G_even` is the gain 332 for green pixels on even rows of the output, and `G_odd` 333 is the gain for green pixels on the odd rows. 334 335 If a HAL does not support a separate gain for even/odd green 336 channels, it must use the `G_even` value, and write 337 `G_odd` equal to `G_even` in the output result metadata. 338 </hal_details> 339 </entry> 340 <entry name="aberrationMode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 341 <enum> 342 <value>OFF 343 <notes> 344 No aberration correction is applied. 345 </notes> 346 </value> 347 <value>FAST 348 <notes> 349 Aberration correction will not slow down capture rate 350 relative to sensor raw output. 351 </notes> 352 </value> 353 <value>HIGH_QUALITY 354 <notes> 355 Aberration correction operates at improved quality but the capture rate might be 356 reduced (relative to sensor raw output rate) 357 </notes> 358 </value> 359 </enum> 360 <description> 361 Mode of operation for the chromatic aberration correction algorithm. 362 </description> 363 <range>android.colorCorrection.availableAberrationModes</range> 364 <details> 365 Chromatic (color) aberration is caused by the fact that different wavelengths of light 366 can not focus on the same point after exiting from the lens. This metadata defines 367 the high level control of chromatic aberration correction algorithm, which aims to 368 minimize the chromatic artifacts that may occur along the object boundaries in an 369 image. 370 371 FAST/HIGH_QUALITY both mean that camera device determined aberration 372 correction will be applied. HIGH_QUALITY mode indicates that the camera device will 373 use the highest-quality aberration correction algorithms, even if it slows down 374 capture rate. FAST means the camera device will not slow down capture rate when 375 applying aberration correction. 376 377 LEGACY devices will always be in FAST mode. 378 </details> 379 </entry> 380 </controls> 381 <dynamic> 382 <clone entry="android.colorCorrection.mode" kind="controls"> 383 </clone> 384 <clone entry="android.colorCorrection.transform" kind="controls"> 385 </clone> 386 <clone entry="android.colorCorrection.gains" kind="controls"> 387 </clone> 388 <clone entry="android.colorCorrection.aberrationMode" kind="controls"> 389 </clone> 390 </dynamic> 391 <static> 392 <entry name="availableAberrationModes" type="byte" visibility="public" 393 type_notes="list of enums" container="array" typedef="enumList" hwlevel="legacy"> 394 <array> 395 <size>n</size> 396 </array> 397 <description> 398 List of aberration correction modes for android.colorCorrection.aberrationMode that are 399 supported by this camera device. 400 </description> 401 <range>Any value listed in android.colorCorrection.aberrationMode</range> 402 <details> 403 This key lists the valid modes for android.colorCorrection.aberrationMode. If no 404 aberration correction modes are available for a device, this list will solely include 405 OFF mode. All camera devices will support either OFF or FAST mode. 406 407 Camera devices that support the MANUAL_POST_PROCESSING capability will always list 408 OFF mode. This includes all FULL level devices. 409 410 LEGACY devices will always only support FAST mode. 411 </details> 412 <hal_details> 413 HAL must support both FAST and HIGH_QUALITY if chromatic aberration control is available 414 on the camera device, but the underlying implementation can be the same for both modes. 415 That is, if the highest quality implementation on the camera device does not slow down 416 capture rate, then FAST and HIGH_QUALITY will generate the same output. 417 </hal_details> 418 <tag id="V1" /> 419 </entry> 420 </static> 421 </section> 422 <section name="control"> 423 <controls> 424 <entry name="aeAntibandingMode" type="byte" visibility="public" 425 enum="true" hwlevel="legacy"> 426 <enum> 427 <value>OFF 428 <notes> 429 The camera device will not adjust exposure duration to 430 avoid banding problems. 431 </notes> 432 </value> 433 <value>50HZ 434 <notes> 435 The camera device will adjust exposure duration to 436 avoid banding problems with 50Hz illumination sources. 437 </notes> 438 </value> 439 <value>60HZ 440 <notes> 441 The camera device will adjust exposure duration to 442 avoid banding problems with 60Hz illumination 443 sources. 444 </notes> 445 </value> 446 <value>AUTO 447 <notes> 448 The camera device will automatically adapt its 449 antibanding routine to the current illumination 450 condition. This is the default mode if AUTO is 451 available on given camera device. 452 </notes> 453 </value> 454 </enum> 455 <description> 456 The desired setting for the camera device's auto-exposure 457 algorithm's antibanding compensation. 458 </description> 459 <range> 460 android.control.aeAvailableAntibandingModes 461 </range> 462 <details> 463 Some kinds of lighting fixtures, such as some fluorescent 464 lights, flicker at the rate of the power supply frequency 465 (60Hz or 50Hz, depending on country). While this is 466 typically not noticeable to a person, it can be visible to 467 a camera device. If a camera sets its exposure time to the 468 wrong value, the flicker may become visible in the 469 viewfinder as flicker or in a final captured image, as a 470 set of variable-brightness bands across the image. 471 472 Therefore, the auto-exposure routines of camera devices 473 include antibanding routines that ensure that the chosen 474 exposure value will not cause such banding. The choice of 475 exposure time depends on the rate of flicker, which the 476 camera device can detect automatically, or the expected 477 rate can be selected by the application using this 478 control. 479 480 A given camera device may not support all of the possible 481 options for the antibanding mode. The 482 android.control.aeAvailableAntibandingModes key contains 483 the available modes for a given camera device. 484 485 AUTO mode is the default if it is available on given 486 camera device. When AUTO mode is not available, the 487 default will be either 50HZ or 60HZ, and both 50HZ 488 and 60HZ will be available. 489 490 If manual exposure control is enabled (by setting 491 android.control.aeMode or android.control.mode to OFF), 492 then this setting has no effect, and the application must 493 ensure it selects exposure times that do not cause banding 494 issues. The android.statistics.sceneFlicker key can assist 495 the application in this. 496 </details> 497 <hal_details> 498 For all capture request templates, this field must be set 499 to AUTO if AUTO mode is available. If AUTO is not available, 500 the default must be either 50HZ or 60HZ, and both 50HZ and 501 60HZ must be available. 502 503 If manual exposure control is enabled (by setting 504 android.control.aeMode or android.control.mode to OFF), 505 then the exposure values provided by the application must not be 506 adjusted for antibanding. 507 </hal_details> 508 <tag id="BC" /> 509 </entry> 510 <entry name="aeExposureCompensation" type="int32" visibility="public" hwlevel="legacy"> 511 <description>Adjustment to auto-exposure (AE) target image 512 brightness.</description> 513 <units>Compensation steps</units> 514 <range>android.control.aeCompensationRange</range> 515 <details> 516 The adjustment is measured as a count of steps, with the 517 step size defined by android.control.aeCompensationStep and the 518 allowed range by android.control.aeCompensationRange. 519 520 For example, if the exposure value (EV) step is 0.333, '6' 521 will mean an exposure compensation of +2 EV; -3 will mean an 522 exposure compensation of -1 EV. One EV represents a doubling 523 of image brightness. Note that this control will only be 524 effective if android.control.aeMode `!=` OFF. This control 525 will take effect even when android.control.aeLock `== true`. 526 527 In the event of exposure compensation value being changed, camera device 528 may take several frames to reach the newly requested exposure target. 529 During that time, android.control.aeState field will be in the SEARCHING 530 state. Once the new exposure target is reached, android.control.aeState will 531 change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or 532 FLASH_REQUIRED (if the scene is too dark for still capture). 533 </details> 534 <tag id="BC" /> 535 </entry> 536 <entry name="aeLock" type="byte" visibility="public" enum="true" 537 typedef="boolean" hwlevel="legacy"> 538 <enum> 539 <value>OFF 540 <notes>Auto-exposure lock is disabled; the AE algorithm 541 is free to update its parameters.</notes></value> 542 <value>ON 543 <notes>Auto-exposure lock is enabled; the AE algorithm 544 must not update the exposure and sensitivity parameters 545 while the lock is active. 546 547 android.control.aeExposureCompensation setting changes 548 will still take effect while auto-exposure is locked. 549 550 Some rare LEGACY devices may not support 551 this, in which case the value will always be overridden to OFF. 552 </notes></value> 553 </enum> 554 <description>Whether auto-exposure (AE) is currently locked to its latest 555 calculated values.</description> 556 <details> 557 When set to `true` (ON), the AE algorithm is locked to its latest parameters, 558 and will not change exposure settings until the lock is set to `false` (OFF). 559 560 Note that even when AE is locked, the flash may be fired if 561 the android.control.aeMode is ON_AUTO_FLASH / 562 ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE. 563 564 When android.control.aeExposureCompensation is changed, even if the AE lock 565 is ON, the camera device will still adjust its exposure value. 566 567 If AE precapture is triggered (see android.control.aePrecaptureTrigger) 568 when AE is already locked, the camera device will not change the exposure time 569 (android.sensor.exposureTime) and sensitivity (android.sensor.sensitivity) 570 parameters. The flash may be fired if the android.control.aeMode 571 is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the 572 android.control.aeMode is ON_ALWAYS_FLASH, the scene may become overexposed. 573 Similarly, AE precapture trigger CANCEL has no effect when AE is already locked. 574 575 When an AE precapture sequence is triggered, AE unlock will not be able to unlock 576 the AE if AE is locked by the camera device internally during precapture metering 577 sequence In other words, submitting requests with AE unlock has no effect for an 578 ongoing precapture metering sequence. Otherwise, the precapture metering sequence 579 will never succeed in a sequence of preview requests where AE lock is always set 580 to `false`. 581 582 Since the camera device has a pipeline of in-flight requests, the settings that 583 get locked do not necessarily correspond to the settings that were present in the 584 latest capture result received from the camera device, since additional captures 585 and AE updates may have occurred even before the result was sent out. If an 586 application is switching between automatic and manual control and wishes to eliminate 587 any flicker during the switch, the following procedure is recommended: 588 589 1. Starting in auto-AE mode: 590 2. Lock AE 591 3. Wait for the first result to be output that has the AE locked 592 4. Copy exposure settings from that result into a request, set the request to manual AE 593 5. Submit the capture request, proceed to run manual AE as desired. 594 595 See android.control.aeState for AE lock related state transition details. 596 </details> 597 <tag id="BC" /> 598 </entry> 599 <entry name="aeMode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 600 <enum> 601 <value>OFF 602 <notes> 603 The camera device's autoexposure routine is disabled. 604 605 The application-selected android.sensor.exposureTime, 606 android.sensor.sensitivity and 607 android.sensor.frameDuration are used by the camera 608 device, along with android.flash.* fields, if there's 609 a flash unit for this camera device. 610 611 Note that auto-white balance (AWB) and auto-focus (AF) 612 behavior is device dependent when AE is in OFF mode. 613 To have consistent behavior across different devices, 614 it is recommended to either set AWB and AF to OFF mode 615 or lock AWB and AF before setting AE to OFF. 616 See android.control.awbMode, android.control.afMode, 617 android.control.awbLock, and android.control.afTrigger 618 for more details. 619 620 LEGACY devices do not support the OFF mode and will 621 override attempts to use this value to ON. 622 </notes> 623 </value> 624 <value>ON 625 <notes> 626 The camera device's autoexposure routine is active, 627 with no flash control. 628 629 The application's values for 630 android.sensor.exposureTime, 631 android.sensor.sensitivity, and 632 android.sensor.frameDuration are ignored. The 633 application has control over the various 634 android.flash.* fields. 635 </notes> 636 </value> 637 <value>ON_AUTO_FLASH 638 <notes> 639 Like ON, except that the camera device also controls 640 the camera's flash unit, firing it in low-light 641 conditions. 642 643 The flash may be fired during a precapture sequence 644 (triggered by android.control.aePrecaptureTrigger) and 645 may be fired for captures for which the 646 android.control.captureIntent field is set to 647 STILL_CAPTURE 648 </notes> 649 </value> 650 <value>ON_ALWAYS_FLASH 651 <notes> 652 Like ON, except that the camera device also controls 653 the camera's flash unit, always firing it for still 654 captures. 655 656 The flash may be fired during a precapture sequence 657 (triggered by android.control.aePrecaptureTrigger) and 658 will always be fired for captures for which the 659 android.control.captureIntent field is set to 660 STILL_CAPTURE 661 </notes> 662 </value> 663 <value>ON_AUTO_FLASH_REDEYE 664 <notes> 665 Like ON_AUTO_FLASH, but with automatic red eye 666 reduction. 667 668 If deemed necessary by the camera device, a red eye 669 reduction flash will fire during the precapture 670 sequence. 671 </notes> 672 </value> 673 <value hal_version="3.3">ON_EXTERNAL_FLASH 674 <notes> 675 An external flash has been turned on. 676 677 It informs the camera device that an external flash has been turned on, and that 678 metering (and continuous focus if active) should be quickly recalculated to account 679 for the external flash. Otherwise, this mode acts like ON. 680 681 When the external flash is turned off, AE mode should be changed to one of the 682 other available AE modes. 683 684 If the camera device supports AE external flash mode, android.control.aeState must 685 be FLASH_REQUIRED after the camera device finishes AE scan and it's too dark without 686 flash. 687 </notes> 688 </value> 689 <value optional="true" hal_version="3.10" 690 aconfig_flag="camera_ae_mode_low_light_boost">ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY 691 <notes> 692 Like 'ON' but applies additional brightness boost in low light scenes. 693 694 When the scene lighting conditions are within the range defined by 695 android.control.lowLightBoostInfoLuminanceRange this mode will apply additional 696 brightness boost. 697 698 This mode will automatically adjust the intensity of low light boost applied 699 according to the scene lighting conditions. A darker scene will receive more boost 700 while a brighter scene will receive less boost. 701 702 This mode can ignore the set target frame rate to allow more light to be captured 703 which can result in choppier motion. The frame rate can extend to lower than the 704 android.control.aeAvailableTargetFpsRanges but will not go below 10 FPS. This mode 705 can also increase the sensor sensitivity gain which can result in increased luma 706 and chroma noise. The sensor sensitivity gain can extend to higher values beyond 707 android.sensor.info.sensitivityRange. This mode may also apply additional 708 processing to recover details in dark and bright areas of the image,and noise 709 reduction at high sensitivity gain settings to manage the trade-off between light 710 sensitivity and capture noise. 711 712 This mode is restricted to two output surfaces. One output surface type can either 713 be SurfaceView or TextureView. Another output surface type can either be MediaCodec 714 or MediaRecorder. This mode cannot be used with a target FPS range higher than 30 715 FPS. 716 717 If the session configuration is not supported, the AE mode reported in the 718 CaptureResult will be 'ON' instead of 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY'. 719 720 When this AE mode is enabled, the CaptureResult field 721 android.control.lowLightBoostState will indicate when low light boost is 'ACTIVE' 722 or 'INACTIVE'. By default android.control.lowLightBoostState will be 'INACTIVE'. 723 724 The low light boost is 'ACTIVE' once the scene lighting condition is less than the 725 upper bound lux value defined by android.control.lowLightBoostInfoLuminanceRange. 726 This mode will be 'INACTIVE' once the scene lighting condition is greater than the 727 upper bound lux value defined by android.control.lowLightBoostInfoLuminanceRange. 728 </notes> 729 </value> 730 </enum> 731 <description>The desired mode for the camera device's 732 auto-exposure routine.</description> 733 <range>android.control.aeAvailableModes</range> 734 <details> 735 This control is only effective if android.control.mode is 736 AUTO. 737 738 When set to any of the ON modes, the camera device's 739 auto-exposure routine is enabled, overriding the 740 application's selected exposure time, sensor sensitivity, 741 and frame duration (android.sensor.exposureTime, 742 android.sensor.sensitivity, and 743 android.sensor.frameDuration). If one of the FLASH modes 744 is selected, the camera device's flash unit controls are 745 also overridden. 746 747 The FLASH modes are only available if the camera device 748 has a flash unit (android.flash.info.available is `true`). 749 750 If flash TORCH mode is desired, this field must be set to 751 ON or OFF, and android.flash.mode set to TORCH. 752 753 When set to any of the ON modes, the values chosen by the 754 camera device auto-exposure routine for the overridden 755 fields for a given capture will be available in its 756 CaptureResult. 757 </details> 758 <tag id="BC" /> 759 </entry> 760 <entry name="aeRegions" type="int32" visibility="public" 761 optional="true" container="array" typedef="meteringRectangle"> 762 <array> 763 <size>5</size> 764 <size>area_count</size> 765 </array> 766 <description>List of metering areas to use for auto-exposure adjustment.</description> 767 <units>Pixel coordinates within android.sensor.info.activeArraySize or 768 android.sensor.info.preCorrectionActiveArraySize depending on 769 distortion correction capability and mode</units> 770 <range>Coordinates must be between `[(0,0), (width, height))` of 771 android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize 772 depending on distortion correction capability and mode</range> 773 <details> 774 Not available if android.control.maxRegionsAe is 0. 775 Otherwise will always be present. 776 777 The maximum number of regions supported by the device is determined by the value 778 of android.control.maxRegionsAe. 779 780 For devices not supporting android.distortionCorrection.mode control, the coordinate 781 system always follows that of android.sensor.info.activeArraySize, with (0,0) being 782 the top-left pixel in the active pixel array, and 783 (android.sensor.info.activeArraySize.width - 1, 784 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 785 active pixel array. 786 787 For devices supporting android.distortionCorrection.mode control, the coordinate 788 system depends on the mode being set. 789 When the distortion correction mode is OFF, the coordinate system follows 790 android.sensor.info.preCorrectionActiveArraySize, with 791 `(0, 0)` being the top-left pixel of the pre-correction active array, and 792 (android.sensor.info.preCorrectionActiveArraySize.width - 1, 793 android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right 794 pixel in the pre-correction active pixel array. 795 When the distortion correction mode is not OFF, the coordinate system follows 796 android.sensor.info.activeArraySize, with 797 `(0, 0)` being the top-left pixel of the active array, and 798 (android.sensor.info.activeArraySize.width - 1, 799 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 800 active pixel array. 801 802 The weight must be within `[0, 1000]`, and represents a weight 803 for every pixel in the area. This means that a large metering area 804 with the same weight as a smaller area will have more effect in 805 the metering result. Metering areas can partially overlap and the 806 camera device will add the weights in the overlap region. 807 808 The weights are relative to weights of other exposure metering regions, so if only one 809 region is used, all non-zero weights will have the same effect. A region with 0 810 weight is ignored. 811 812 If all regions have 0 weight, then no specific metering area needs to be used by the 813 camera device. 814 815 If the metering region is outside the used android.scaler.cropRegion returned in 816 capture result metadata, the camera device will ignore the sections outside the crop 817 region and output only the intersection rectangle as the metering region in the result 818 metadata. If the region is entirely outside the crop region, it will be ignored and 819 not reported in the result metadata. 820 821 When setting the AE metering regions, the application must consider the additional 822 crop resulted from the aspect ratio differences between the preview stream and 823 android.scaler.cropRegion. For example, if the android.scaler.cropRegion is the full 824 active array size with 4:3 aspect ratio, and the preview stream is 16:9, 825 the boundary of AE regions will be [0, y_crop] and 826 [active_width, active_height - 2 * y_crop] rather than [0, 0] and 827 [active_width, active_height], where y_crop is the additional crop due to aspect ratio 828 mismatch. 829 830 Starting from API level 30, the coordinate system of activeArraySize or 831 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 832 pre-zoom field of view. This means that the same aeRegions values at different 833 android.control.zoomRatio represent different parts of the scene. The aeRegions 834 coordinates are relative to the activeArray/preCorrectionActiveArray representing the 835 zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same 836 aeRegions at different android.scaler.cropRegion still represent the same parts of the 837 scene as they do before. See android.control.zoomRatio for details. Whether to use 838 activeArraySize or preCorrectionActiveArraySize still depends on distortion correction 839 mode. 840 841 For camera devices with the 842 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 843 capability or devices where 844 {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 845 lists {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode} 846 android.sensor.info.activeArraySizeMaximumResolution / 847 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 848 coordinate system for requests where android.sensor.pixelMode is set to 849 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 850 </details> 851 <ndk_details> 852 The data representation is `int[5 * area_count]`. 853 Every five elements represent a metering region of `(xmin, ymin, xmax, ymax, weight)`. 854 The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and 855 ymax. 856 </ndk_details> 857 <hal_details> 858 The HAL level representation of MeteringRectangle[] is a 859 int[5 * area_count]. 860 Every five elements represent a metering region of 861 (xmin, ymin, xmax, ymax, weight). 862 The rectangle is defined to be inclusive on xmin and ymin, but 863 exclusive on xmax and ymax. 864 HAL must always report metering regions in the coordinate system of pre-correction 865 active array. 866 </hal_details> 867 <tag id="BC" /> 868 </entry> 869 <entry name="aeTargetFpsRange" type="int32" visibility="public" 870 container="array" typedef="rangeInt" hwlevel="legacy"> 871 <array> 872 <size>2</size> 873 </array> 874 <description>Range over which the auto-exposure routine can 875 adjust the capture frame rate to maintain good 876 exposure.</description> 877 <units>Frames per second (FPS)</units> 878 <range>Any of the entries in android.control.aeAvailableTargetFpsRanges</range> 879 <details>Only constrains auto-exposure (AE) algorithm, not 880 manual control of android.sensor.exposureTime and 881 android.sensor.frameDuration. 882 883 Note that the actual achievable max framerate also depends on the minimum frame 884 duration of the output streams. The max frame rate will be 885 `min(aeTargetFpsRange.maxFps, 1 / max(individual stream min durations))`. For example, 886 if the application sets this key to `{60, 60}`, but the maximum minFrameDuration among 887 all configured streams is 33ms, the maximum framerate won't be 60fps, but will be 888 30fps. 889 890 To start a CaptureSession with a target FPS range different from the 891 capture request template's default value, the application 892 is strongly recommended to call 893 {@link android.hardware.camera2.params.SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters} 894 with the target fps range before creating the capture session. The aeTargetFpsRange is 895 typically a session parameter. Specifying it at session creation time helps avoid 896 session reconfiguration delays in cases like 60fps or high speed recording. 897 </details> 898 <tag id="BC" /> 899 </entry> 900 <entry name="aePrecaptureTrigger" type="byte" visibility="public" 901 enum="true" hwlevel="limited"> 902 <enum> 903 <value>IDLE 904 <notes>The trigger is idle.</notes> 905 </value> 906 <value>START 907 <notes>The precapture metering sequence will be started 908 by the camera device. 909 910 The exact effect of the precapture trigger depends on 911 the current AE mode and state.</notes> 912 </value> 913 <value>CANCEL 914 <notes>The camera device will cancel any currently active or completed 915 precapture metering sequence, the auto-exposure routine will return to its 916 initial state.</notes> 917 </value> 918 </enum> 919 <description>Whether the camera device will trigger a precapture 920 metering sequence when it processes this request.</description> 921 <details>This entry is normally set to IDLE, or is not 922 included at all in the request settings. When included and 923 set to START, the camera device will trigger the auto-exposure (AE) 924 precapture metering sequence. 925 926 When set to CANCEL, the camera device will cancel any active 927 precapture metering trigger, and return to its initial AE state. 928 If a precapture metering sequence is already completed, and the camera 929 device has implicitly locked the AE for subsequent still capture, the 930 CANCEL trigger will unlock the AE and return to its initial AE state. 931 932 The precapture sequence should be triggered before starting a 933 high-quality still capture for final metering decisions to 934 be made, and for firing pre-capture flash pulses to estimate 935 scene brightness and required final capture flash power, when 936 the flash is enabled. 937 938 Normally, this entry should be set to START for only a 939 single request, and the application should wait until the 940 sequence completes before starting a new one. 941 942 When a precapture metering sequence is finished, the camera device 943 may lock the auto-exposure routine internally to be able to accurately expose the 944 subsequent still capture image (`android.control.captureIntent == STILL_CAPTURE`). 945 For this case, the AE may not resume normal scan if no subsequent still capture is 946 submitted. To ensure that the AE routine restarts normal scan, the application should 947 submit a request with `android.control.aeLock == true`, followed by a request 948 with `android.control.aeLock == false`, if the application decides not to submit a 949 still capture request after the precapture sequence completes. Alternatively, for 950 API level 23 or newer devices, the CANCEL can be used to unlock the camera device 951 internally locked AE if the application doesn't submit a still capture request after 952 the AE precapture trigger. Note that, the CANCEL was added in API level 23, and must not 953 be used in devices that have earlier API levels. 954 955 The exact effect of auto-exposure (AE) precapture trigger 956 depends on the current AE mode and state; see 957 android.control.aeState for AE precapture state transition 958 details. 959 960 On LEGACY-level devices, the precapture trigger is not supported; 961 capturing a high-resolution JPEG image will automatically trigger a 962 precapture sequence before the high-resolution capture, including 963 potentially firing a pre-capture flash. 964 965 Using the precapture trigger and the auto-focus trigger android.control.afTrigger 966 simultaneously is allowed. However, since these triggers often require cooperation between 967 the auto-focus and auto-exposure routines (for example, the may need to be enabled for a 968 focus sweep), the camera device may delay acting on a later trigger until the previous 969 trigger has been fully handled. This may lead to longer intervals between the trigger and 970 changes to android.control.aeState indicating the start of the precapture sequence, for 971 example. 972 973 If both the precapture and the auto-focus trigger are activated on the same request, then 974 the camera device will complete them in the optimal order for that device. 975 </details> 976 <hal_details> 977 The HAL must support triggering the AE precapture trigger while an AF trigger is active 978 (and vice versa), or at the same time as the AF trigger. It is acceptable for the HAL to 979 treat these as two consecutive triggers, for example handling the AF trigger and then the 980 AE trigger. Or the HAL may choose to optimize the case with both triggers fired at once, 981 to minimize the latency for converging both focus and exposure/flash usage. 982 </hal_details> 983 <tag id="BC" /> 984 </entry> 985 <entry name="afMode" type="byte" visibility="public" enum="true" 986 hwlevel="legacy"> 987 <enum> 988 <value>OFF 989 <notes>The auto-focus routine does not control the lens; 990 android.lens.focusDistance is controlled by the 991 application.</notes></value> 992 <value>AUTO 993 <notes>Basic automatic focus mode. 994 995 In this mode, the lens does not move unless 996 the autofocus trigger action is called. When that trigger 997 is activated, AF will transition to ACTIVE_SCAN, then to 998 the outcome of the scan (FOCUSED or NOT_FOCUSED). 999 1000 Always supported if lens is not fixed focus. 1001 1002 Use android.lens.info.minimumFocusDistance to determine if lens 1003 is fixed-focus. 1004 1005 Triggering AF_CANCEL resets the lens position to default, 1006 and sets the AF state to INACTIVE.</notes></value> 1007 <value>MACRO 1008 <notes>Close-up focusing mode. 1009 1010 In this mode, the lens does not move unless the 1011 autofocus trigger action is called. When that trigger is 1012 activated, AF will transition to ACTIVE_SCAN, then to 1013 the outcome of the scan (FOCUSED or NOT_FOCUSED). This 1014 mode is optimized for focusing on objects very close to 1015 the camera. 1016 1017 When that trigger is activated, AF will transition to 1018 ACTIVE_SCAN, then to the outcome of the scan (FOCUSED or 1019 NOT_FOCUSED). Triggering cancel AF resets the lens 1020 position to default, and sets the AF state to 1021 INACTIVE.</notes></value> 1022 <value>CONTINUOUS_VIDEO 1023 <notes>In this mode, the AF algorithm modifies the lens 1024 position continually to attempt to provide a 1025 constantly-in-focus image stream. 1026 1027 The focusing behavior should be suitable for good quality 1028 video recording; typically this means slower focus 1029 movement and no overshoots. When the AF trigger is not 1030 involved, the AF algorithm should start in INACTIVE state, 1031 and then transition into PASSIVE_SCAN and PASSIVE_FOCUSED 1032 states as appropriate. When the AF trigger is activated, 1033 the algorithm should immediately transition into 1034 AF_FOCUSED or AF_NOT_FOCUSED as appropriate, and lock the 1035 lens position until a cancel AF trigger is received. 1036 1037 Once cancel is received, the algorithm should transition 1038 back to INACTIVE and resume passive scan. Note that this 1039 behavior is not identical to CONTINUOUS_PICTURE, since an 1040 ongoing PASSIVE_SCAN must immediately be 1041 canceled.</notes></value> 1042 <value>CONTINUOUS_PICTURE 1043 <notes>In this mode, the AF algorithm modifies the lens 1044 position continually to attempt to provide a 1045 constantly-in-focus image stream. 1046 1047 The focusing behavior should be suitable for still image 1048 capture; typically this means focusing as fast as 1049 possible. When the AF trigger is not involved, the AF 1050 algorithm should start in INACTIVE state, and then 1051 transition into PASSIVE_SCAN and PASSIVE_FOCUSED states as 1052 appropriate as it attempts to maintain focus. When the AF 1053 trigger is activated, the algorithm should finish its 1054 PASSIVE_SCAN if active, and then transition into 1055 AF_FOCUSED or AF_NOT_FOCUSED as appropriate, and lock the 1056 lens position until a cancel AF trigger is received. 1057 1058 When the AF cancel trigger is activated, the algorithm 1059 should transition back to INACTIVE and then act as if it 1060 has just been started.</notes></value> 1061 <value>EDOF 1062 <notes>Extended depth of field (digital focus) mode. 1063 1064 The camera device will produce images with an extended 1065 depth of field automatically; no special focusing 1066 operations need to be done before taking a picture. 1067 1068 AF triggers are ignored, and the AF state will always be 1069 INACTIVE.</notes></value> 1070 </enum> 1071 <description>Whether auto-focus (AF) is currently enabled, and what 1072 mode it is set to.</description> 1073 <range>android.control.afAvailableModes</range> 1074 <details>Only effective if android.control.mode = AUTO and the lens is not fixed focus 1075 (i.e. `android.lens.info.minimumFocusDistance > 0`). Also note that 1076 when android.control.aeMode is OFF, the behavior of AF is device 1077 dependent. It is recommended to lock AF by using android.control.afTrigger before 1078 setting android.control.aeMode to OFF, or set AF mode to OFF when AE is OFF. 1079 1080 If the lens is controlled by the camera device auto-focus algorithm, 1081 the camera device will report the current AF status in android.control.afState 1082 in result metadata.</details> 1083 <hal_details> 1084 When afMode is AUTO or MACRO, the lens must not move until an AF trigger is sent in a 1085 request (android.control.afTrigger `==` START). After an AF trigger, the afState will end 1086 up with either FOCUSED_LOCKED or NOT_FOCUSED_LOCKED state (see 1087 android.control.afState for detailed state transitions), which indicates that the lens is 1088 locked and will not move. If camera movement (e.g. tilting camera) causes the lens to move 1089 after the lens is locked, the HAL must compensate this movement appropriately such that 1090 the same focal plane remains in focus. 1091 1092 When afMode is one of the continuous auto focus modes, the HAL is free to start a AF 1093 scan whenever it's not locked. When the lens is locked after an AF trigger 1094 (see android.control.afState for detailed state transitions), the HAL should maintain the 1095 same lock behavior as above. 1096 1097 When afMode is OFF, the application controls focus manually. The accuracy of the 1098 focus distance control depends on the android.lens.info.focusDistanceCalibration. 1099 However, the lens must not move regardless of the camera movement for any focus distance 1100 manual control. 1101 1102 To put this in concrete terms, if the camera has lens elements which may move based on 1103 camera orientation or motion (e.g. due to gravity), then the HAL must drive the lens to 1104 remain in a fixed position invariant to the camera's orientation or motion, for example, 1105 by using accelerometer measurements in the lens control logic. This is a typical issue 1106 that will arise on camera modules with open-loop VCMs. 1107 </hal_details> 1108 <tag id="BC" /> 1109 </entry> 1110 <entry name="afRegions" type="int32" visibility="public" 1111 optional="true" container="array" typedef="meteringRectangle"> 1112 <array> 1113 <size>5</size> 1114 <size>area_count</size> 1115 </array> 1116 <description>List of metering areas to use for auto-focus.</description> 1117 <units>Pixel coordinates within android.sensor.info.activeArraySize or 1118 android.sensor.info.preCorrectionActiveArraySize depending on 1119 distortion correction capability and mode</units> 1120 <range>Coordinates must be between `[(0,0), (width, height))` of 1121 android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize 1122 depending on distortion correction capability and mode</range> 1123 <details> 1124 Not available if android.control.maxRegionsAf is 0. 1125 Otherwise will always be present. 1126 1127 The maximum number of focus areas supported by the device is determined by the value 1128 of android.control.maxRegionsAf. 1129 1130 1131 For devices not supporting android.distortionCorrection.mode control, the coordinate 1132 system always follows that of android.sensor.info.activeArraySize, with (0,0) being 1133 the top-left pixel in the active pixel array, and 1134 (android.sensor.info.activeArraySize.width - 1, 1135 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1136 active pixel array. 1137 1138 For devices supporting android.distortionCorrection.mode control, the coordinate 1139 system depends on the mode being set. 1140 When the distortion correction mode is OFF, the coordinate system follows 1141 android.sensor.info.preCorrectionActiveArraySize, with 1142 `(0, 0)` being the top-left pixel of the pre-correction active array, and 1143 (android.sensor.info.preCorrectionActiveArraySize.width - 1, 1144 android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right 1145 pixel in the pre-correction active pixel array. 1146 When the distortion correction mode is not OFF, the coordinate system follows 1147 android.sensor.info.activeArraySize, with 1148 `(0, 0)` being the top-left pixel of the active array, and 1149 (android.sensor.info.activeArraySize.width - 1, 1150 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1151 active pixel array. 1152 1153 The weight must be within `[0, 1000]`, and represents a weight 1154 for every pixel in the area. This means that a large metering area 1155 with the same weight as a smaller area will have more effect in 1156 the metering result. Metering areas can partially overlap and the 1157 camera device will add the weights in the overlap region. 1158 1159 The weights are relative to weights of other metering regions, so if only one region 1160 is used, all non-zero weights will have the same effect. A region with 0 weight is 1161 ignored. 1162 1163 If all regions have 0 weight, then no specific metering area needs to be used by the 1164 camera device. The capture result will either be a zero weight region as well, or 1165 the region selected by the camera device as the focus area of interest. 1166 1167 If the metering region is outside the used android.scaler.cropRegion returned in 1168 capture result metadata, the camera device will ignore the sections outside the crop 1169 region and output only the intersection rectangle as the metering region in the result 1170 metadata. If the region is entirely outside the crop region, it will be ignored and 1171 not reported in the result metadata. 1172 1173 When setting the AF metering regions, the application must consider the additional 1174 crop resulted from the aspect ratio differences between the preview stream and 1175 android.scaler.cropRegion. For example, if the android.scaler.cropRegion is the full 1176 active array size with 4:3 aspect ratio, and the preview stream is 16:9, 1177 the boundary of AF regions will be [0, y_crop] and 1178 [active_width, active_height - 2 * y_crop] rather than [0, 0] and 1179 [active_width, active_height], where y_crop is the additional crop due to aspect ratio 1180 mismatch. 1181 1182 Starting from API level 30, the coordinate system of activeArraySize or 1183 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 1184 pre-zoom field of view. This means that the same afRegions values at different 1185 android.control.zoomRatio represent different parts of the scene. The afRegions 1186 coordinates are relative to the activeArray/preCorrectionActiveArray representing the 1187 zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same 1188 afRegions at different android.scaler.cropRegion still represent the same parts of the 1189 scene as they do before. See android.control.zoomRatio for details. Whether to use 1190 activeArraySize or preCorrectionActiveArraySize still depends on distortion correction 1191 mode. 1192 1193 For camera devices with the 1194 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 1195 capability or devices where 1196 {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 1197 lists {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode}, 1198 android.sensor.info.activeArraySizeMaximumResolution / 1199 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 1200 coordinate system for requests where android.sensor.pixelMode is set to 1201 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 1202 </details> 1203 <ndk_details> 1204 The data representation is `int[5 * area_count]`. 1205 Every five elements represent a metering region of `(xmin, ymin, xmax, ymax, weight)`. 1206 The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and 1207 ymax. 1208 </ndk_details> 1209 <hal_details> 1210 The HAL level representation of MeteringRectangle[] is a 1211 int[5 * area_count]. 1212 Every five elements represent a metering region of 1213 (xmin, ymin, xmax, ymax, weight). 1214 The rectangle is defined to be inclusive on xmin and ymin, but 1215 exclusive on xmax and ymax. 1216 HAL must always report metering regions in the coordinate system of pre-correction 1217 active array. 1218 </hal_details> 1219 <tag id="BC" /> 1220 </entry> 1221 <entry name="afTrigger" type="byte" visibility="public" enum="true" 1222 hwlevel="legacy"> 1223 <enum> 1224 <value>IDLE 1225 <notes>The trigger is idle.</notes> 1226 </value> 1227 <value>START 1228 <notes>Autofocus will trigger now.</notes> 1229 </value> 1230 <value>CANCEL 1231 <notes>Autofocus will return to its initial 1232 state, and cancel any currently active trigger.</notes> 1233 </value> 1234 </enum> 1235 <description> 1236 Whether the camera device will trigger autofocus for this request. 1237 </description> 1238 <details>This entry is normally set to IDLE, or is not 1239 included at all in the request settings. 1240 1241 When included and set to START, the camera device will trigger the 1242 autofocus algorithm. If autofocus is disabled, this trigger has no effect. 1243 1244 When set to CANCEL, the camera device will cancel any active trigger, 1245 and return to its initial AF state. 1246 1247 Generally, applications should set this entry to START or CANCEL for only a 1248 single capture, and then return it to IDLE (or not set at all). Specifying 1249 START for multiple captures in a row means restarting the AF operation over 1250 and over again. 1251 1252 See android.control.afState for what the trigger means for each AF mode. 1253 1254 Using the autofocus trigger and the precapture trigger android.control.aePrecaptureTrigger 1255 simultaneously is allowed. However, since these triggers often require cooperation between 1256 the auto-focus and auto-exposure routines (for example, the may need to be enabled for a 1257 focus sweep), the camera device may delay acting on a later trigger until the previous 1258 trigger has been fully handled. This may lead to longer intervals between the trigger and 1259 changes to android.control.afState, for example. 1260 </details> 1261 <hal_details> 1262 The HAL must support triggering the AF trigger while an AE precapture trigger is active 1263 (and vice versa), or at the same time as the AE trigger. It is acceptable for the HAL to 1264 treat these as two consecutive triggers, for example handling the AF trigger and then the 1265 AE trigger. Or the HAL may choose to optimize the case with both triggers fired at once, 1266 to minimize the latency for converging both focus and exposure/flash usage. 1267 </hal_details> 1268 <tag id="BC" /> 1269 </entry> 1270 <entry name="awbLock" type="byte" visibility="public" enum="true" 1271 typedef="boolean" hwlevel="legacy"> 1272 <enum> 1273 <value>OFF 1274 <notes>Auto-white balance lock is disabled; the AWB 1275 algorithm is free to update its parameters if in AUTO 1276 mode.</notes></value> 1277 <value>ON 1278 <notes>Auto-white balance lock is enabled; the AWB 1279 algorithm will not update its parameters while the lock 1280 is active.</notes></value> 1281 </enum> 1282 <description>Whether auto-white balance (AWB) is currently locked to its 1283 latest calculated values.</description> 1284 <details> 1285 When set to `true` (ON), the AWB algorithm is locked to its latest parameters, 1286 and will not change color balance settings until the lock is set to `false` (OFF). 1287 1288 Since the camera device has a pipeline of in-flight requests, the settings that 1289 get locked do not necessarily correspond to the settings that were present in the 1290 latest capture result received from the camera device, since additional captures 1291 and AWB updates may have occurred even before the result was sent out. If an 1292 application is switching between automatic and manual control and wishes to eliminate 1293 any flicker during the switch, the following procedure is recommended: 1294 1295 1. Starting in auto-AWB mode: 1296 2. Lock AWB 1297 3. Wait for the first result to be output that has the AWB locked 1298 4. Copy AWB settings from that result into a request, set the request to manual AWB 1299 5. Submit the capture request, proceed to run manual AWB as desired. 1300 1301 Note that AWB lock is only meaningful when 1302 android.control.awbMode is in the AUTO mode; in other modes, 1303 AWB is already fixed to a specific setting. 1304 1305 Some LEGACY devices may not support ON; the value is then overridden to OFF. 1306 </details> 1307 <tag id="BC" /> 1308 </entry> 1309 <entry name="awbMode" type="byte" visibility="public" enum="true" 1310 hwlevel="legacy"> 1311 <enum> 1312 <value>OFF 1313 <notes> 1314 The camera device's auto-white balance routine is disabled. 1315 1316 The application-selected color transform matrix 1317 (android.colorCorrection.transform) and gains 1318 (android.colorCorrection.gains) are used by the camera 1319 device for manual white balance control. 1320 </notes> 1321 </value> 1322 <value>AUTO 1323 <notes> 1324 The camera device's auto-white balance routine is active. 1325 1326 The application's values for android.colorCorrection.transform 1327 and android.colorCorrection.gains are ignored. 1328 For devices that support the MANUAL_POST_PROCESSING capability, the 1329 values used by the camera device for the transform and gains 1330 will be available in the capture result for this request. 1331 </notes> 1332 </value> 1333 <value>INCANDESCENT 1334 <notes> 1335 The camera device's auto-white balance routine is disabled; 1336 the camera device uses incandescent light as the assumed scene 1337 illumination for white balance. 1338 1339 While the exact white balance transforms are up to the 1340 camera device, they will approximately match the CIE 1341 standard illuminant A. 1342 1343 The application's values for android.colorCorrection.transform 1344 and android.colorCorrection.gains are ignored. 1345 For devices that support the MANUAL_POST_PROCESSING capability, the 1346 values used by the camera device for the transform and gains 1347 will be available in the capture result for this request. 1348 </notes> 1349 </value> 1350 <value>FLUORESCENT 1351 <notes> 1352 The camera device's auto-white balance routine is disabled; 1353 the camera device uses fluorescent light as the assumed scene 1354 illumination for white balance. 1355 1356 While the exact white balance transforms are up to the 1357 camera device, they will approximately match the CIE 1358 standard illuminant F2. 1359 1360 The application's values for android.colorCorrection.transform 1361 and android.colorCorrection.gains are ignored. 1362 For devices that support the MANUAL_POST_PROCESSING capability, the 1363 values used by the camera device for the transform and gains 1364 will be available in the capture result for this request. 1365 </notes> 1366 </value> 1367 <value>WARM_FLUORESCENT 1368 <notes> 1369 The camera device's auto-white balance routine is disabled; 1370 the camera device uses warm fluorescent light as the assumed scene 1371 illumination for white balance. 1372 1373 While the exact white balance transforms are up to the 1374 camera device, they will approximately match the CIE 1375 standard illuminant F4. 1376 1377 The application's values for android.colorCorrection.transform 1378 and android.colorCorrection.gains are ignored. 1379 For devices that support the MANUAL_POST_PROCESSING capability, the 1380 values used by the camera device for the transform and gains 1381 will be available in the capture result for this request. 1382 </notes> 1383 </value> 1384 <value>DAYLIGHT 1385 <notes> 1386 The camera device's auto-white balance routine is disabled; 1387 the camera device uses daylight light as the assumed scene 1388 illumination for white balance. 1389 1390 While the exact white balance transforms are up to the 1391 camera device, they will approximately match the CIE 1392 standard illuminant D65. 1393 1394 The application's values for android.colorCorrection.transform 1395 and android.colorCorrection.gains are ignored. 1396 For devices that support the MANUAL_POST_PROCESSING capability, the 1397 values used by the camera device for the transform and gains 1398 will be available in the capture result for this request. 1399 </notes> 1400 </value> 1401 <value>CLOUDY_DAYLIGHT 1402 <notes> 1403 The camera device's auto-white balance routine is disabled; 1404 the camera device uses cloudy daylight light as the assumed scene 1405 illumination for white balance. 1406 1407 The application's values for android.colorCorrection.transform 1408 and android.colorCorrection.gains are ignored. 1409 For devices that support the MANUAL_POST_PROCESSING capability, the 1410 values used by the camera device for the transform and gains 1411 will be available in the capture result for this request. 1412 </notes> 1413 </value> 1414 <value>TWILIGHT 1415 <notes> 1416 The camera device's auto-white balance routine is disabled; 1417 the camera device uses twilight light as the assumed scene 1418 illumination for white balance. 1419 1420 The application's values for android.colorCorrection.transform 1421 and android.colorCorrection.gains are ignored. 1422 For devices that support the MANUAL_POST_PROCESSING capability, the 1423 values used by the camera device for the transform and gains 1424 will be available in the capture result for this request. 1425 </notes> 1426 </value> 1427 <value>SHADE 1428 <notes> 1429 The camera device's auto-white balance routine is disabled; 1430 the camera device uses shade light as the assumed scene 1431 illumination for white balance. 1432 1433 The application's values for android.colorCorrection.transform 1434 and android.colorCorrection.gains are ignored. 1435 For devices that support the MANUAL_POST_PROCESSING capability, the 1436 values used by the camera device for the transform and gains 1437 will be available in the capture result for this request. 1438 </notes> 1439 </value> 1440 </enum> 1441 <description>Whether auto-white balance (AWB) is currently setting the color 1442 transform fields, and what its illumination target 1443 is.</description> 1444 <range>android.control.awbAvailableModes</range> 1445 <details> 1446 This control is only effective if android.control.mode is AUTO. 1447 1448 When set to the AUTO mode, the camera device's auto-white balance 1449 routine is enabled, overriding the application's selected 1450 android.colorCorrection.transform, android.colorCorrection.gains and 1451 android.colorCorrection.mode. Note that when android.control.aeMode 1452 is OFF, the behavior of AWB is device dependent. It is recommended to 1453 also set AWB mode to OFF or lock AWB by using android.control.awbLock before 1454 setting AE mode to OFF. 1455 1456 When set to the OFF mode, the camera device's auto-white balance 1457 routine is disabled. The application manually controls the white 1458 balance by android.colorCorrection.transform, android.colorCorrection.gains 1459 and android.colorCorrection.mode. 1460 1461 When set to any other modes, the camera device's auto-white 1462 balance routine is disabled. The camera device uses each 1463 particular illumination target for white balance 1464 adjustment. The application's values for 1465 android.colorCorrection.transform, 1466 android.colorCorrection.gains and 1467 android.colorCorrection.mode are ignored. 1468 </details> 1469 <tag id="BC" /> 1470 </entry> 1471 <entry name="awbRegions" type="int32" visibility="public" 1472 optional="true" container="array" typedef="meteringRectangle"> 1473 <array> 1474 <size>5</size> 1475 <size>area_count</size> 1476 </array> 1477 <description>List of metering areas to use for auto-white-balance illuminant 1478 estimation.</description> 1479 <units>Pixel coordinates within android.sensor.info.activeArraySize or 1480 android.sensor.info.preCorrectionActiveArraySize depending on 1481 distortion correction capability and mode</units> 1482 <range>Coordinates must be between `[(0,0), (width, height))` of 1483 android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize 1484 depending on distortion correction capability and mode</range> 1485 <details> 1486 Not available if android.control.maxRegionsAwb is 0. 1487 Otherwise will always be present. 1488 1489 The maximum number of regions supported by the device is determined by the value 1490 of android.control.maxRegionsAwb. 1491 1492 For devices not supporting android.distortionCorrection.mode control, the coordinate 1493 system always follows that of android.sensor.info.activeArraySize, with (0,0) being 1494 the top-left pixel in the active pixel array, and 1495 (android.sensor.info.activeArraySize.width - 1, 1496 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1497 active pixel array. 1498 1499 For devices supporting android.distortionCorrection.mode control, the coordinate 1500 system depends on the mode being set. 1501 When the distortion correction mode is OFF, the coordinate system follows 1502 android.sensor.info.preCorrectionActiveArraySize, with 1503 `(0, 0)` being the top-left pixel of the pre-correction active array, and 1504 (android.sensor.info.preCorrectionActiveArraySize.width - 1, 1505 android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right 1506 pixel in the pre-correction active pixel array. 1507 When the distortion correction mode is not OFF, the coordinate system follows 1508 android.sensor.info.activeArraySize, with 1509 `(0, 0)` being the top-left pixel of the active array, and 1510 (android.sensor.info.activeArraySize.width - 1, 1511 android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the 1512 active pixel array. 1513 1514 The weight must range from 0 to 1000, and represents a weight 1515 for every pixel in the area. This means that a large metering area 1516 with the same weight as a smaller area will have more effect in 1517 the metering result. Metering areas can partially overlap and the 1518 camera device will add the weights in the overlap region. 1519 1520 The weights are relative to weights of other white balance metering regions, so if 1521 only one region is used, all non-zero weights will have the same effect. A region with 1522 0 weight is ignored. 1523 1524 If all regions have 0 weight, then no specific metering area needs to be used by the 1525 camera device. 1526 1527 If the metering region is outside the used android.scaler.cropRegion returned in 1528 capture result metadata, the camera device will ignore the sections outside the crop 1529 region and output only the intersection rectangle as the metering region in the result 1530 metadata. If the region is entirely outside the crop region, it will be ignored and 1531 not reported in the result metadata. 1532 1533 When setting the AWB metering regions, the application must consider the additional 1534 crop resulted from the aspect ratio differences between the preview stream and 1535 android.scaler.cropRegion. For example, if the android.scaler.cropRegion is the full 1536 active array size with 4:3 aspect ratio, and the preview stream is 16:9, 1537 the boundary of AWB regions will be [0, y_crop] and 1538 [active_width, active_height - 2 * y_crop] rather than [0, 0] and 1539 [active_width, active_height], where y_crop is the additional crop due to aspect ratio 1540 mismatch. 1541 1542 Starting from API level 30, the coordinate system of activeArraySize or 1543 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 1544 pre-zoom field of view. This means that the same awbRegions values at different 1545 android.control.zoomRatio represent different parts of the scene. The awbRegions 1546 coordinates are relative to the activeArray/preCorrectionActiveArray representing the 1547 zoomed field of view. If android.control.zoomRatio is set to 1.0 (default), the same 1548 awbRegions at different android.scaler.cropRegion still represent the same parts of 1549 the scene as they do before. See android.control.zoomRatio for details. Whether to use 1550 activeArraySize or preCorrectionActiveArraySize still depends on distortion correction 1551 mode. 1552 1553 For camera devices with the 1554 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 1555 capability or devices where 1556 {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 1557 lists {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode}, 1558 android.sensor.info.activeArraySizeMaximumResolution / 1559 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 1560 coordinate system for requests where android.sensor.pixelMode is set to 1561 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 1562 </details> 1563 <ndk_details> 1564 The data representation is `int[5 * area_count]`. 1565 Every five elements represent a metering region of `(xmin, ymin, xmax, ymax, weight)`. 1566 The rectangle is defined to be inclusive on xmin and ymin, but exclusive on xmax and 1567 ymax. 1568 </ndk_details> 1569 <hal_details> 1570 The HAL level representation of MeteringRectangle[] is a 1571 int[5 * area_count]. 1572 Every five elements represent a metering region of 1573 (xmin, ymin, xmax, ymax, weight). 1574 The rectangle is defined to be inclusive on xmin and ymin, but 1575 exclusive on xmax and ymax. 1576 HAL must always report metering regions in the coordinate system of pre-correction 1577 active array. 1578 </hal_details> 1579 <tag id="BC" /> 1580 </entry> 1581 <entry name="captureIntent" type="byte" visibility="public" enum="true" 1582 hwlevel="legacy"> 1583 <enum> 1584 <value>CUSTOM 1585 <notes>The goal of this request doesn't fall into the other 1586 categories. The camera device will default to preview-like 1587 behavior.</notes></value> 1588 <value>PREVIEW 1589 <notes>This request is for a preview-like use case. 1590 1591 The precapture trigger may be used to start off a metering 1592 w/flash sequence. 1593 </notes></value> 1594 <value>STILL_CAPTURE 1595 <notes>This request is for a still capture-type 1596 use case. 1597 1598 If the flash unit is under automatic control, it may fire as needed. 1599 </notes></value> 1600 <value>VIDEO_RECORD 1601 <notes>This request is for a video recording 1602 use case.</notes></value> 1603 <value>VIDEO_SNAPSHOT 1604 <notes>This request is for a video snapshot (still 1605 image while recording video) use case. 1606 1607 The camera device should take the highest-quality image 1608 possible (given the other settings) without disrupting the 1609 frame rate of video recording. </notes></value> 1610 <value>ZERO_SHUTTER_LAG 1611 <notes>This request is for a ZSL usecase; the 1612 application will stream full-resolution images and 1613 reprocess one or several later for a final 1614 capture. 1615 </notes></value> 1616 <value>MANUAL 1617 <notes>This request is for manual capture use case where 1618 the applications want to directly control the capture parameters. 1619 1620 For example, the application may wish to manually control 1621 android.sensor.exposureTime, android.sensor.sensitivity, etc. 1622 </notes></value> 1623 <value hal_version="3.3">MOTION_TRACKING 1624 <notes>This request is for a motion tracking use case, where 1625 the application will use camera and inertial sensor data to 1626 locate and track objects in the world. 1627 1628 The camera device auto-exposure routine will limit the exposure time 1629 of the camera to no more than 20 milliseconds, to minimize motion blur. 1630 </notes></value> 1631 </enum> 1632 <description>Information to the camera device 3A (auto-exposure, 1633 auto-focus, auto-white balance) routines about the purpose 1634 of this capture, to help the camera device to decide optimal 3A 1635 strategy.</description> 1636 <details>This control (except for MANUAL) is only effective if 1637 `android.control.mode != OFF` and any 3A routine is active. 1638 1639 All intents are supported by all devices, except that: 1640 1641 * ZERO_SHUTTER_LAG will be supported if android.request.availableCapabilities contains 1642 PRIVATE_REPROCESSING or YUV_REPROCESSING. 1643 * MANUAL will be supported if android.request.availableCapabilities contains 1644 MANUAL_SENSOR. 1645 * MOTION_TRACKING will be supported if android.request.availableCapabilities contains 1646 MOTION_TRACKING. 1647 </details> 1648 <tag id="BC" /> 1649 </entry> 1650 <entry name="effectMode" type="byte" visibility="public" enum="true" 1651 hwlevel="legacy"> 1652 <enum> 1653 <value>OFF 1654 <notes> 1655 No color effect will be applied. 1656 </notes> 1657 </value> 1658 <value optional="true">MONO 1659 <notes> 1660 A "monocolor" effect where the image is mapped into 1661 a single color. 1662 1663 This will typically be grayscale. 1664 </notes> 1665 </value> 1666 <value optional="true">NEGATIVE 1667 <notes> 1668 A "photo-negative" effect where the image's colors 1669 are inverted. 1670 </notes> 1671 </value> 1672 <value optional="true">SOLARIZE 1673 <notes> 1674 A "solarisation" effect (Sabattier effect) where the 1675 image is wholly or partially reversed in 1676 tone. 1677 </notes> 1678 </value> 1679 <value optional="true">SEPIA 1680 <notes> 1681 A "sepia" effect where the image is mapped into warm 1682 gray, red, and brown tones. 1683 </notes> 1684 </value> 1685 <value optional="true">POSTERIZE 1686 <notes> 1687 A "posterization" effect where the image uses 1688 discrete regions of tone rather than a continuous 1689 gradient of tones. 1690 </notes> 1691 </value> 1692 <value optional="true">WHITEBOARD 1693 <notes> 1694 A "whiteboard" effect where the image is typically displayed 1695 as regions of white, with black or grey details. 1696 </notes> 1697 </value> 1698 <value optional="true">BLACKBOARD 1699 <notes> 1700 A "blackboard" effect where the image is typically displayed 1701 as regions of black, with white or grey details. 1702 </notes> 1703 </value> 1704 <value optional="true">AQUA 1705 <notes> 1706 An "aqua" effect where a blue hue is added to the image. 1707 </notes> 1708 </value> 1709 </enum> 1710 <description>A special color effect to apply.</description> 1711 <range>android.control.availableEffects</range> 1712 <details> 1713 When this mode is set, a color effect will be applied 1714 to images produced by the camera device. The interpretation 1715 and implementation of these color effects is left to the 1716 implementor of the camera device, and should not be 1717 depended on to be consistent (or present) across all 1718 devices. 1719 </details> 1720 <tag id="BC" /> 1721 </entry> 1722 <entry name="mode" type="byte" visibility="public" enum="true" 1723 hwlevel="legacy"> 1724 <enum> 1725 <value>OFF 1726 <notes>Full application control of pipeline. 1727 1728 All control by the device's metering and focusing (3A) 1729 routines is disabled, and no other settings in 1730 android.control.* have any effect, except that 1731 android.control.captureIntent may be used by the camera 1732 device to select post-processing values for processing 1733 blocks that do not allow for manual control, or are not 1734 exposed by the camera API. 1735 1736 However, the camera device's 3A routines may continue to 1737 collect statistics and update their internal state so that 1738 when control is switched to AUTO mode, good control values 1739 can be immediately applied. 1740 </notes></value> 1741 <value>AUTO 1742 <notes>Use settings for each individual 3A routine. 1743 1744 Manual control of capture parameters is disabled. All 1745 controls in android.control.* besides sceneMode take 1746 effect.</notes></value> 1747 <value optional="true">USE_SCENE_MODE 1748 <notes>Use a specific scene mode. 1749 1750 Enabling this disables control.aeMode, control.awbMode and 1751 control.afMode controls; the camera device will ignore 1752 those settings while USE_SCENE_MODE is active (except for 1753 FACE_PRIORITY scene mode). Other control entries are still active. 1754 This setting can only be used if scene mode is supported (i.e. 1755 android.control.availableSceneModes 1756 contain some modes other than DISABLED). 1757 1758 For extended scene modes such as BOKEH, please use USE_EXTENDED_SCENE_MODE instead. 1759 </notes></value> 1760 <value optional="true">OFF_KEEP_STATE 1761 <notes>Same as OFF mode, except that this capture will not be 1762 used by camera device background auto-exposure, auto-white balance and 1763 auto-focus algorithms (3A) to update their statistics. 1764 1765 Specifically, the 3A routines are locked to the last 1766 values set from a request with AUTO, OFF, or 1767 USE_SCENE_MODE, and any statistics or state updates 1768 collected from manual captures with OFF_KEEP_STATE will be 1769 discarded by the camera device. 1770 </notes></value> 1771 <value optional="true" hal_version="3.5">USE_EXTENDED_SCENE_MODE 1772 <notes>Use a specific extended scene mode. 1773 1774 When extended scene mode is on, the camera device may override certain control 1775 parameters, such as targetFpsRange, AE, AWB, and AF modes, to achieve best power and 1776 quality tradeoffs. Only the mandatory stream combinations of LIMITED hardware level 1777 are guaranteed. 1778 1779 This setting can only be used if extended scene mode is supported (i.e. 1780 android.control.availableExtendedSceneModes 1781 contains some modes other than DISABLED).</notes></value> 1782 </enum> 1783 <description>Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control 1784 routines.</description> 1785 <range>android.control.availableModes</range> 1786 <details> 1787 This is a top-level 3A control switch. When set to OFF, all 3A control 1788 by the camera device is disabled. The application must set the fields for 1789 capture parameters itself. 1790 1791 When set to AUTO, the individual algorithm controls in 1792 android.control.* are in effect, such as android.control.afMode. 1793 1794 When set to USE_SCENE_MODE or USE_EXTENDED_SCENE_MODE, the individual controls in 1795 android.control.* are mostly disabled, and the camera device 1796 implements one of the scene mode or extended scene mode settings (such as ACTION, 1797 SUNSET, PARTY, or BOKEH) as it wishes. The camera device scene mode 1798 3A settings are provided by {@link 1799 android.hardware.camera2.CaptureResult|ACameraCaptureSession_captureCallback_result 1800 capture results}. 1801 1802 When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference 1803 is that this frame will not be used by camera device background 3A statistics 1804 update, as if this frame is never captured. This mode can be used in the scenario 1805 where the application doesn't want a 3A manual control capture to affect 1806 the subsequent auto 3A capture results. 1807 </details> 1808 <tag id="BC" /> 1809 </entry> 1810 <entry name="sceneMode" type="byte" visibility="public" enum="true" 1811 hwlevel="legacy"> 1812 <enum> 1813 <value id="0">DISABLED 1814 <notes> 1815 Indicates that no scene modes are set for a given capture request. 1816 </notes> 1817 </value> 1818 <value>FACE_PRIORITY 1819 <notes>If face detection support exists, use face 1820 detection data for auto-focus, auto-white balance, and 1821 auto-exposure routines. 1822 1823 If face detection statistics are disabled 1824 (i.e. android.statistics.faceDetectMode is set to OFF), 1825 this should still operate correctly (but will not return 1826 face detection statistics to the framework). 1827 1828 Unlike the other scene modes, android.control.aeMode, 1829 android.control.awbMode, and android.control.afMode 1830 remain active when FACE_PRIORITY is set. 1831 </notes> 1832 </value> 1833 <value optional="true">ACTION 1834 <notes> 1835 Optimized for photos of quickly moving objects. 1836 1837 Similar to SPORTS. 1838 </notes> 1839 </value> 1840 <value optional="true">PORTRAIT 1841 <notes> 1842 Optimized for still photos of people. 1843 </notes> 1844 </value> 1845 <value optional="true">LANDSCAPE 1846 <notes> 1847 Optimized for photos of distant macroscopic objects. 1848 </notes> 1849 </value> 1850 <value optional="true">NIGHT 1851 <notes> 1852 Optimized for low-light settings. 1853 </notes> 1854 </value> 1855 <value optional="true">NIGHT_PORTRAIT 1856 <notes> 1857 Optimized for still photos of people in low-light 1858 settings. 1859 </notes> 1860 </value> 1861 <value optional="true">THEATRE 1862 <notes> 1863 Optimized for dim, indoor settings where flash must 1864 remain off. 1865 </notes> 1866 </value> 1867 <value optional="true">BEACH 1868 <notes> 1869 Optimized for bright, outdoor beach settings. 1870 </notes> 1871 </value> 1872 <value optional="true">SNOW 1873 <notes> 1874 Optimized for bright, outdoor settings containing snow. 1875 </notes> 1876 </value> 1877 <value optional="true">SUNSET 1878 <notes> 1879 Optimized for scenes of the setting sun. 1880 </notes> 1881 </value> 1882 <value optional="true">STEADYPHOTO 1883 <notes> 1884 Optimized to avoid blurry photos due to small amounts of 1885 device motion (for example: due to hand shake). 1886 </notes> 1887 </value> 1888 <value optional="true">FIREWORKS 1889 <notes> 1890 Optimized for nighttime photos of fireworks. 1891 </notes> 1892 </value> 1893 <value optional="true">SPORTS 1894 <notes> 1895 Optimized for photos of quickly moving people. 1896 1897 Similar to ACTION. 1898 </notes> 1899 </value> 1900 <value optional="true">PARTY 1901 <notes> 1902 Optimized for dim, indoor settings with multiple moving 1903 people. 1904 </notes> 1905 </value> 1906 <value optional="true">CANDLELIGHT 1907 <notes> 1908 Optimized for dim settings where the main light source 1909 is a candle. 1910 </notes> 1911 </value> 1912 <value optional="true">BARCODE 1913 <notes> 1914 Optimized for accurately capturing a photo of barcode 1915 for use by camera applications that wish to read the 1916 barcode value. 1917 </notes> 1918 </value> 1919 <value deprecated="true" optional="true" visibility="java_public">HIGH_SPEED_VIDEO 1920 <notes> 1921 This is deprecated, please use {@link 1922 android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession} 1923 and {@link 1924 android.hardware.camera2.CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList} 1925 for high speed video recording. 1926 1927 Optimized for high speed video recording (frame rate >=60fps) use case. 1928 1929 The supported high speed video sizes and fps ranges are specified in 1930 android.control.availableHighSpeedVideoConfigurations. To get desired 1931 output frame rates, the application is only allowed to select video size 1932 and fps range combinations listed in this static metadata. The fps range 1933 can be control via android.control.aeTargetFpsRange. 1934 1935 In this mode, the camera device will override aeMode, awbMode, and afMode to 1936 ON, ON, and CONTINUOUS_VIDEO, respectively. All post-processing block mode 1937 controls will be overridden to be FAST. Therefore, no manual control of capture 1938 and post-processing parameters is possible. All other controls operate the 1939 same as when android.control.mode == AUTO. This means that all other 1940 android.control.* fields continue to work, such as 1941 1942 * android.control.aeTargetFpsRange 1943 * android.control.aeExposureCompensation 1944 * android.control.aeLock 1945 * android.control.awbLock 1946 * android.control.effectMode 1947 * android.control.aeRegions 1948 * android.control.afRegions 1949 * android.control.awbRegions 1950 * android.control.afTrigger 1951 * android.control.aePrecaptureTrigger 1952 * android.control.zoomRatio 1953 1954 Outside of android.control.*, the following controls will work: 1955 1956 * android.flash.mode (automatic flash for still capture will not work since aeMode is ON) 1957 * android.lens.opticalStabilizationMode (if it is supported) 1958 * android.scaler.cropRegion 1959 * android.statistics.faceDetectMode 1960 1961 For high speed recording use case, the actual maximum supported frame rate may 1962 be lower than what camera can output, depending on the destination Surfaces for 1963 the image data. For example, if the destination surface is from video encoder, 1964 the application need check if the video encoder is capable of supporting the 1965 high frame rate for a given video size, or it will end up with lower recording 1966 frame rate. If the destination surface is from preview window, the preview frame 1967 rate will be bounded by the screen refresh rate. 1968 1969 The camera device will only support up to 2 output high speed streams 1970 (processed non-stalling format defined in android.request.maxNumOutputStreams) 1971 in this mode. This control will be effective only if all of below conditions are true: 1972 1973 * The application created no more than maxNumHighSpeedStreams processed non-stalling 1974 format output streams, where maxNumHighSpeedStreams is calculated as 1975 min(2, android.request.maxNumOutputStreams[Processed (but not-stalling)]). 1976 * The stream sizes are selected from the sizes reported by 1977 android.control.availableHighSpeedVideoConfigurations. 1978 * No processed non-stalling or raw streams are configured. 1979 1980 When above conditions are NOT satisfied, the controls of this mode and 1981 android.control.aeTargetFpsRange will be ignored by the camera device, 1982 the camera device will fall back to android.control.mode `==` AUTO, 1983 and the returned capture result metadata will give the fps range chosen 1984 by the camera device. 1985 1986 Switching into or out of this mode may trigger some camera ISP/sensor 1987 reconfigurations, which may introduce extra latency. It is recommended that 1988 the application avoids unnecessary scene mode switch as much as possible. 1989 </notes> 1990 </value> 1991 <value optional="true">HDR 1992 <notes> 1993 Turn on a device-specific high dynamic range (HDR) mode. 1994 1995 In this scene mode, the camera device captures images 1996 that keep a larger range of scene illumination levels 1997 visible in the final image. For example, when taking a 1998 picture of a object in front of a bright window, both 1999 the object and the scene through the window may be 2000 visible when using HDR mode, while in normal AUTO mode, 2001 one or the other may be poorly exposed. As a tradeoff, 2002 HDR mode generally takes much longer to capture a single 2003 image, has no user control, and may have other artifacts 2004 depending on the HDR method used. 2005 2006 Therefore, HDR captures operate at a much slower rate 2007 than regular captures. 2008 2009 In this mode, on LIMITED or FULL devices, when a request 2010 is made with a android.control.captureIntent of 2011 STILL_CAPTURE, the camera device will capture an image 2012 using a high dynamic range capture technique. On LEGACY 2013 devices, captures that target a JPEG-format output will 2014 be captured with HDR, and the capture intent is not 2015 relevant. 2016 2017 The HDR capture may involve the device capturing a burst 2018 of images internally and combining them into one, or it 2019 may involve the device using specialized high dynamic 2020 range capture hardware. In all cases, a single image is 2021 produced in response to a capture request submitted 2022 while in HDR mode. 2023 2024 Since substantial post-processing is generally needed to 2025 produce an HDR image, only YUV, PRIVATE, and JPEG 2026 outputs are supported for LIMITED/FULL device HDR 2027 captures, and only JPEG outputs are supported for LEGACY 2028 HDR captures. Using a RAW output for HDR capture is not 2029 supported. 2030 2031 Some devices may also support always-on HDR, which 2032 applies HDR processing at full frame rate. For these 2033 devices, intents other than STILL_CAPTURE will also 2034 produce an HDR output with no frame rate impact compared 2035 to normal operation, though the quality may be lower 2036 than for STILL_CAPTURE intents. 2037 2038 If SCENE_MODE_HDR is used with unsupported output types 2039 or capture intents, the images captured will be as if 2040 the SCENE_MODE was not enabled at all. 2041 </notes> 2042 </value> 2043 <value optional="true" visibility="hidden">FACE_PRIORITY_LOW_LIGHT 2044 <notes>Same as FACE_PRIORITY scene mode, except that the camera 2045 device will choose higher sensitivity values (android.sensor.sensitivity) 2046 under low light conditions. 2047 2048 The camera device may be tuned to expose the images in a reduced 2049 sensitivity range to produce the best quality images. For example, 2050 if the android.sensor.info.sensitivityRange gives range of [100, 1600], 2051 the camera device auto-exposure routine tuning process may limit the actual 2052 exposure sensitivity range to [100, 1200] to ensure that the noise level isn't 2053 excessive in order to preserve the image quality. Under this situation, the image under 2054 low light may be under-exposed when the sensor max exposure time (bounded by the 2055 android.control.aeTargetFpsRange when android.control.aeMode is one of the 2056 ON_* modes) and effective max sensitivity are reached. This scene mode allows the 2057 camera device auto-exposure routine to increase the sensitivity up to the max 2058 sensitivity specified by android.sensor.info.sensitivityRange when the scene is too 2059 dark and the max exposure time is reached. The captured images may be noisier 2060 compared with the images captured in normal FACE_PRIORITY mode; therefore, it is 2061 recommended that the application only use this scene mode when it is capable of 2062 reducing the noise level of the captured images. 2063 2064 Unlike the other scene modes, android.control.aeMode, 2065 android.control.awbMode, and android.control.afMode 2066 remain active when FACE_PRIORITY_LOW_LIGHT is set. 2067 </notes> 2068 </value> 2069 <value optional="true" visibility="hidden" id="100">DEVICE_CUSTOM_START 2070 <notes> 2071 Scene mode values within the range of 2072 `[DEVICE_CUSTOM_START, DEVICE_CUSTOM_END]` are reserved for device specific 2073 customized scene modes. 2074 </notes> 2075 </value> 2076 <value optional="true" visibility="hidden" id="127">DEVICE_CUSTOM_END 2077 <notes> 2078 Scene mode values within the range of 2079 `[DEVICE_CUSTOM_START, DEVICE_CUSTOM_END]` are reserved for device specific 2080 customized scene modes. 2081 </notes> 2082 </value> 2083 </enum> 2084 <description> 2085 Control for which scene mode is currently active. 2086 </description> 2087 <range>android.control.availableSceneModes</range> 2088 <details> 2089 Scene modes are custom camera modes optimized for a certain set of conditions and 2090 capture settings. 2091 2092 This is the mode that that is active when 2093 `android.control.mode == USE_SCENE_MODE`. Aside from FACE_PRIORITY, these modes will 2094 disable android.control.aeMode, android.control.awbMode, and android.control.afMode 2095 while in use. 2096 2097 The interpretation and implementation of these scene modes is left 2098 to the implementor of the camera device. Their behavior will not be 2099 consistent across all devices, and any given device may only implement 2100 a subset of these modes. 2101 </details> 2102 <hal_details> 2103 HAL implementations that include scene modes are expected to provide 2104 the per-scene settings to use for android.control.aeMode, 2105 android.control.awbMode, and android.control.afMode in 2106 android.control.sceneModeOverrides. 2107 2108 For HIGH_SPEED_VIDEO mode, if it is included in android.control.availableSceneModes, the 2109 HAL must list supported video size and fps range in 2110 android.control.availableHighSpeedVideoConfigurations. For a given size, e.g. 1280x720, 2111 if the HAL has two different sensor configurations for normal streaming mode and high 2112 speed streaming, when this scene mode is set/reset in a sequence of capture requests, the 2113 HAL may have to switch between different sensor modes. This mode is deprecated in legacy 2114 HAL3.3, to support high speed video recording, please implement 2115 android.control.availableHighSpeedVideoConfigurations and CONSTRAINED_HIGH_SPEED_VIDEO 2116 capability defined in android.request.availableCapabilities. 2117 </hal_details> 2118 <tag id="BC" /> 2119 </entry> 2120 <entry name="videoStabilizationMode" type="byte" visibility="public" 2121 enum="true" hwlevel="legacy"> 2122 <enum> 2123 <value>OFF 2124 <notes> 2125 Video stabilization is disabled. 2126 </notes></value> 2127 <value>ON 2128 <notes> 2129 Video stabilization is enabled. 2130 </notes></value> 2131 <value optional="true" hal_version="3.8">PREVIEW_STABILIZATION 2132 <notes> 2133 Preview stabilization, where the preview in addition to all other non-RAW streams are 2134 stabilized with the same quality of stabilization, is enabled. This mode aims to give 2135 clients a 'what you see is what you get' effect. In this mode, the FoV reduction will 2136 be a maximum of 20 % both horizontally and vertically 2137 (10% from left, right, top, bottom) for the given zoom ratio / crop region. 2138 The resultant FoV will also be the same across all processed streams 2139 (that have the same aspect ratio). 2140 </notes></value> 2141 </enum> 2142 <description>Whether video stabilization is 2143 active.</description> 2144 <details> 2145 Video stabilization automatically warps images from 2146 the camera in order to stabilize motion between consecutive frames. 2147 2148 If enabled, video stabilization can modify the 2149 android.scaler.cropRegion to keep the video stream stabilized. 2150 2151 Switching between different video stabilization modes may take several 2152 frames to initialize, the camera device will report the current mode 2153 in capture result metadata. For example, When "ON" mode is requested, 2154 the video stabilization modes in the first several capture results may 2155 still be "OFF", and it will become "ON" when the initialization is 2156 done. 2157 2158 In addition, not all recording sizes or frame rates may be supported for 2159 stabilization by a device that reports stabilization support. It is guaranteed 2160 that an output targeting a MediaRecorder or MediaCodec will be stabilized if 2161 the recording resolution is less than or equal to 1920 x 1080 (width less than 2162 or equal to 1920, height less than or equal to 1080), and the recording 2163 frame rate is less than or equal to 30fps. At other sizes, the CaptureResult 2164 android.control.videoStabilizationMode field will return 2165 OFF if the recording output is not stabilized, or if there are no output 2166 Surface types that can be stabilized. 2167 2168 The application is strongly recommended to call 2169 {@link android.hardware.camera2.params.SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters} 2170 with the desired video stabilization mode before creating the capture session. 2171 Video stabilization mode is a session parameter on many devices. Specifying 2172 it at session creation time helps avoid reconfiguration delay caused by difference 2173 between the default value and the first CaptureRequest. 2174 2175 If a camera device supports both this mode and OIS 2176 (android.lens.opticalStabilizationMode), turning both modes on may 2177 produce undesirable interaction, so it is recommended not to enable 2178 both at the same time. 2179 2180 If video stabilization is set to "PREVIEW_STABILIZATION", 2181 android.lens.opticalStabilizationMode is overridden. The camera sub-system may choose 2182 to turn on hardware based image stabilization in addition to software based stabilization 2183 if it deems that appropriate. 2184 This key may be a part of the available session keys, which camera clients may 2185 query via 2186 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys|ACameraManager_getCameraCharacteristics}. 2187 If this is the case, changing this key over the life-time of a capture session may 2188 cause delays / glitches. 2189 2190 </details> 2191 <hal_details> 2192 When this key is set to "PREVIEW_STABILIZATION", 2193 for non-stalling buffers returned without errors, the time interval between notify readout 2194 timestamp and when buffers are returned to the camera framework, must be no more than 1 2195 extra frame interval, relative to the case where this key is set to "OFF". 2196 2197 This is in order for look-ahead time period to be short enough 2198 for preview to match video recording for real-time usage. 2199 </hal_details> 2200 <tag id="BC" /> 2201 </entry> 2202 </controls> 2203 <static> 2204 <entry name="aeAvailableAntibandingModes" type="byte" visibility="public" 2205 type_notes="list of enums" container="array" typedef="enumList" 2206 hwlevel="legacy"> 2207 <array> 2208 <size>n</size> 2209 </array> 2210 <description> 2211 List of auto-exposure antibanding modes for android.control.aeAntibandingMode that are 2212 supported by this camera device. 2213 </description> 2214 <range>Any value listed in android.control.aeAntibandingMode</range> 2215 <details> 2216 Not all of the auto-exposure anti-banding modes may be 2217 supported by a given camera device. This field lists the 2218 valid anti-banding modes that the application may request 2219 for this camera device with the 2220 android.control.aeAntibandingMode control. 2221 </details> 2222 <tag id="BC" /> 2223 </entry> 2224 <entry name="aeAvailableModes" type="byte" visibility="public" 2225 type_notes="list of enums" container="array" typedef="enumList" 2226 hwlevel="legacy"> 2227 <array> 2228 <size>n</size> 2229 </array> 2230 <description> 2231 List of auto-exposure modes for android.control.aeMode that are supported by this camera 2232 device. 2233 </description> 2234 <range>Any value listed in android.control.aeMode</range> 2235 <details> 2236 Not all the auto-exposure modes may be supported by a 2237 given camera device, especially if no flash unit is 2238 available. This entry lists the valid modes for 2239 android.control.aeMode for this camera device. 2240 2241 All camera devices support ON, and all camera devices with flash 2242 units support ON_AUTO_FLASH and ON_ALWAYS_FLASH. 2243 2244 FULL mode camera devices always support OFF mode, 2245 which enables application control of camera exposure time, 2246 sensitivity, and frame duration. 2247 2248 LEGACY mode camera devices never support OFF mode. 2249 LIMITED mode devices support OFF if they support the MANUAL_SENSOR 2250 capability. 2251 </details> 2252 <tag id="BC" /> 2253 </entry> 2254 <entry name="aeAvailableTargetFpsRanges" type="int32" visibility="public" 2255 type_notes="list of pairs of frame rates" 2256 container="array" typedef="rangeInt" 2257 hwlevel="legacy"> 2258 <array> 2259 <size>2</size> 2260 <size>n</size> 2261 </array> 2262 <description>List of frame rate ranges for android.control.aeTargetFpsRange supported by 2263 this camera device.</description> 2264 <units>Frames per second (FPS)</units> 2265 <details> 2266 For devices at the LEGACY level or above: 2267 2268 * For constant-framerate recording, for each normal 2269 {@link android.media.CamcorderProfile CamcorderProfile}, that is, a 2270 {@link android.media.CamcorderProfile CamcorderProfile} that has 2271 {@link android.media.CamcorderProfile#quality quality} in 2272 the range [{@link android.media.CamcorderProfile#QUALITY_LOW QUALITY_LOW}, 2273 {@link android.media.CamcorderProfile#QUALITY_2160P QUALITY_2160P}], if the profile is 2274 supported by the device and has 2275 {@link android.media.CamcorderProfile#videoFrameRate videoFrameRate} `x`, this list will 2276 always include (`x`,`x`). 2277 2278 * Also, a camera device must either not support any 2279 {@link android.media.CamcorderProfile CamcorderProfile}, 2280 or support at least one 2281 normal {@link android.media.CamcorderProfile CamcorderProfile} that has 2282 {@link android.media.CamcorderProfile#videoFrameRate videoFrameRate} `x` >= 24. 2283 2284 For devices at the LIMITED level or above: 2285 2286 * For devices that advertise NIR color filter arrangement in 2287 android.sensor.info.colorFilterArrangement, this list will always include 2288 (`max`, `max`) where `max` = the maximum output frame rate of the maximum YUV_420_888 2289 output size. 2290 * For devices advertising any color filter arrangement other than NIR, or devices not 2291 advertising color filter arrangement, this list will always include (`min`, `max`) and 2292 (`max`, `max`) where `min` <= 15 and `max` = the maximum output frame rate of the 2293 maximum YUV_420_888 output size. 2294 2295 </details> 2296 <hal_details> 2297 HAL must make sure the lower bound and upper bound of each supported targetFpsRange can 2298 be reached. For example, if HAL supports an aeTargetFpsRange of (15, 30), when set by the 2299 application, the camera must be able to reach 15fps in sufficient dark scenes. This way 2300 the application knows the exact range of frame rate it can expect. 2301 </hal_details> 2302 <tag id="BC" /> 2303 </entry> 2304 <entry name="aeCompensationRange" type="int32" visibility="public" 2305 container="array" typedef="rangeInt" 2306 hwlevel="legacy"> 2307 <array> 2308 <size>2</size> 2309 </array> 2310 <description>Maximum and minimum exposure compensation values for 2311 android.control.aeExposureCompensation, in counts of android.control.aeCompensationStep, 2312 that are supported by this camera device.</description> 2313 <range> 2314 Range [0,0] indicates that exposure compensation is not supported. 2315 2316 For LIMITED and FULL devices, range must follow below requirements if exposure 2317 compensation is supported (`range != [0, 0]`): 2318 2319 `Min.exposure compensation * android.control.aeCompensationStep <= -2 EV` 2320 2321 `Max.exposure compensation * android.control.aeCompensationStep >= 2 EV` 2322 2323 LEGACY devices may support a smaller range than this. 2324 </range> 2325 <tag id="BC" /> 2326 </entry> 2327 <entry name="aeCompensationStep" type="rational" visibility="public" 2328 hwlevel="legacy"> 2329 <description>Smallest step by which the exposure compensation 2330 can be changed.</description> 2331 <units>Exposure Value (EV)</units> 2332 <details> 2333 This is the unit for android.control.aeExposureCompensation. For example, if this key has 2334 a value of `1/2`, then a setting of `-2` for android.control.aeExposureCompensation means 2335 that the target EV offset for the auto-exposure routine is -1 EV. 2336 2337 One unit of EV compensation changes the brightness of the captured image by a factor 2338 of two. +1 EV doubles the image brightness, while -1 EV halves the image brightness. 2339 </details> 2340 <hal_details> 2341 This must be less than or equal to 1/2. 2342 </hal_details> 2343 <tag id="BC" /> 2344 </entry> 2345 <entry name="afAvailableModes" type="byte" visibility="public" 2346 type_notes="List of enums" container="array" typedef="enumList" 2347 hwlevel="legacy"> 2348 <array> 2349 <size>n</size> 2350 </array> 2351 <description> 2352 List of auto-focus (AF) modes for android.control.afMode that are 2353 supported by this camera device. 2354 </description> 2355 <range>Any value listed in android.control.afMode</range> 2356 <details> 2357 Not all the auto-focus modes may be supported by a 2358 given camera device. This entry lists the valid modes for 2359 android.control.afMode for this camera device. 2360 2361 All LIMITED and FULL mode camera devices will support OFF mode, and all 2362 camera devices with adjustable focuser units 2363 (`android.lens.info.minimumFocusDistance > 0`) will support AUTO mode. 2364 2365 LEGACY devices will support OFF mode only if they support 2366 focusing to infinity (by also setting android.lens.focusDistance to 2367 `0.0f`). 2368 </details> 2369 <tag id="BC" /> 2370 </entry> 2371 <entry name="availableEffects" type="byte" visibility="public" 2372 type_notes="List of enums (android.control.effectMode)." container="array" 2373 typedef="enumList" hwlevel="legacy"> 2374 <array> 2375 <size>n</size> 2376 </array> 2377 <description> 2378 List of color effects for android.control.effectMode that are supported by this camera 2379 device. 2380 </description> 2381 <range>Any value listed in android.control.effectMode</range> 2382 <details> 2383 This list contains the color effect modes that can be applied to 2384 images produced by the camera device. 2385 Implementations are not expected to be consistent across all devices. 2386 If no color effect modes are available for a device, this will only list 2387 OFF. 2388 2389 A color effect will only be applied if 2390 android.control.mode != OFF. OFF is always included in this list. 2391 2392 This control has no effect on the operation of other control routines such 2393 as auto-exposure, white balance, or focus. 2394 </details> 2395 <tag id="BC" /> 2396 </entry> 2397 <entry name="availableSceneModes" type="byte" visibility="public" 2398 type_notes="List of enums (android.control.sceneMode)." 2399 container="array" typedef="enumList" hwlevel="legacy"> 2400 <array> 2401 <size>n</size> 2402 </array> 2403 <description> 2404 List of scene modes for android.control.sceneMode that are supported by this camera 2405 device. 2406 </description> 2407 <range>Any value listed in android.control.sceneMode</range> 2408 <details> 2409 This list contains scene modes that can be set for the camera device. 2410 Only scene modes that have been fully implemented for the 2411 camera device may be included here. Implementations are not expected 2412 to be consistent across all devices. 2413 2414 If no scene modes are supported by the camera device, this 2415 will be set to DISABLED. Otherwise DISABLED will not be listed. 2416 2417 FACE_PRIORITY is always listed if face detection is 2418 supported (i.e.`android.statistics.info.maxFaceCount > 2419 0`). 2420 </details> 2421 <tag id="BC" /> 2422 </entry> 2423 <entry name="availableVideoStabilizationModes" type="byte" 2424 visibility="public" type_notes="List of enums." container="array" 2425 typedef="enumList" hwlevel="legacy"> 2426 <array> 2427 <size>n</size> 2428 </array> 2429 <description> 2430 List of video stabilization modes for android.control.videoStabilizationMode 2431 that are supported by this camera device. 2432 </description> 2433 <range>Any value listed in android.control.videoStabilizationMode</range> 2434 <details> 2435 OFF will always be listed. 2436 </details> 2437 <tag id="BC" /> 2438 </entry> 2439 <entry name="awbAvailableModes" type="byte" visibility="public" 2440 type_notes="List of enums" 2441 container="array" typedef="enumList" hwlevel="legacy"> 2442 <array> 2443 <size>n</size> 2444 </array> 2445 <description> 2446 List of auto-white-balance modes for android.control.awbMode that are supported by this 2447 camera device. 2448 </description> 2449 <range>Any value listed in android.control.awbMode</range> 2450 <details> 2451 Not all the auto-white-balance modes may be supported by a 2452 given camera device. This entry lists the valid modes for 2453 android.control.awbMode for this camera device. 2454 2455 All camera devices will support ON mode. 2456 2457 Camera devices that support the MANUAL_POST_PROCESSING capability will always support OFF 2458 mode, which enables application control of white balance, by using 2459 android.colorCorrection.transform and android.colorCorrection.gains 2460 (android.colorCorrection.mode must be set to TRANSFORM_MATRIX). This includes all FULL 2461 mode camera devices. 2462 </details> 2463 <tag id="BC" /> 2464 </entry> 2465 <entry name="maxRegions" type="int32" visibility="ndk_public" 2466 container="array" hwlevel="legacy"> 2467 <array> 2468 <size>3</size> 2469 </array> 2470 <description> 2471 List of the maximum number of regions that can be used for metering in 2472 auto-exposure (AE), auto-white balance (AWB), and auto-focus (AF); 2473 this corresponds to the maximum number of elements in 2474 android.control.aeRegions, android.control.awbRegions, 2475 and android.control.afRegions. 2476 </description> 2477 <range> 2478 Value must be &gt;= 0 for each element. For full-capability devices 2479 this value must be &gt;= 1 for AE and AF. The order of the elements is: 2480 `(AE, AWB, AF)`.</range> 2481 <tag id="BC" /> 2482 </entry> 2483 <entry name="maxRegionsAe" type="int32" visibility="java_public" 2484 synthetic="true" hwlevel="legacy"> 2485 <description> 2486 The maximum number of metering regions that can be used by the auto-exposure (AE) 2487 routine. 2488 </description> 2489 <range>Value will be &gt;= 0. For FULL-capability devices, this 2490 value will be &gt;= 1. 2491 </range> 2492 <details> 2493 This corresponds to the maximum allowed number of elements in 2494 android.control.aeRegions. 2495 </details> 2496 <hal_details>This entry is private to the framework. Fill in 2497 maxRegions to have this entry be automatically populated. 2498 </hal_details> 2499 </entry> 2500 <entry name="maxRegionsAwb" type="int32" visibility="java_public" 2501 synthetic="true" hwlevel="legacy"> 2502 <description> 2503 The maximum number of metering regions that can be used by the auto-white balance (AWB) 2504 routine. 2505 </description> 2506 <range>Value will be &gt;= 0. 2507 </range> 2508 <details> 2509 This corresponds to the maximum allowed number of elements in 2510 android.control.awbRegions. 2511 </details> 2512 <hal_details>This entry is private to the framework. Fill in 2513 maxRegions to have this entry be automatically populated. 2514 </hal_details> 2515 </entry> 2516 <entry name="maxRegionsAf" type="int32" visibility="java_public" 2517 synthetic="true" hwlevel="legacy"> 2518 <description> 2519 The maximum number of metering regions that can be used by the auto-focus (AF) routine. 2520 </description> 2521 <range>Value will be &gt;= 0. For FULL-capability devices, this 2522 value will be &gt;= 1. 2523 </range> 2524 <details> 2525 This corresponds to the maximum allowed number of elements in 2526 android.control.afRegions. 2527 </details> 2528 <hal_details>This entry is private to the framework. Fill in 2529 maxRegions to have this entry be automatically populated. 2530 </hal_details> 2531 </entry> 2532 <entry name="sceneModeOverrides" type="byte" visibility="system" 2533 container="array" hwlevel="limited"> 2534 <array> 2535 <size>3</size> 2536 <size>length(availableSceneModes)</size> 2537 </array> 2538 <description> 2539 Ordered list of auto-exposure, auto-white balance, and auto-focus 2540 settings to use with each available scene mode. 2541 </description> 2542 <range> 2543 For each available scene mode, the list must contain three 2544 entries containing the android.control.aeMode, 2545 android.control.awbMode, and android.control.afMode values used 2546 by the camera device. The entry order is `(aeMode, awbMode, afMode)` 2547 where aeMode has the lowest index position. 2548 </range> 2549 <details> 2550 When a scene mode is enabled, the camera device is expected 2551 to override android.control.aeMode, android.control.awbMode, 2552 and android.control.afMode with its preferred settings for 2553 that scene mode. 2554 2555 The order of this list matches that of availableSceneModes, 2556 with 3 entries for each mode. The overrides listed 2557 for FACE_PRIORITY and FACE_PRIORITY_LOW_LIGHT (if supported) are ignored, 2558 since for that mode the application-set android.control.aeMode, 2559 android.control.awbMode, and android.control.afMode values are 2560 used instead, matching the behavior when android.control.mode 2561 is set to AUTO. It is recommended that the FACE_PRIORITY and 2562 FACE_PRIORITY_LOW_LIGHT (if supported) overrides should be set to 0. 2563 2564 For example, if availableSceneModes contains 2565 `(FACE_PRIORITY, ACTION, NIGHT)`, then the camera framework 2566 expects sceneModeOverrides to have 9 entries formatted like: 2567 `(0, 0, 0, ON_AUTO_FLASH, AUTO, CONTINUOUS_PICTURE, 2568 ON_AUTO_FLASH, INCANDESCENT, AUTO)`. 2569 </details> 2570 <hal_details> 2571 To maintain backward compatibility, this list will be made available 2572 in the static metadata of the camera service. The camera service will 2573 use these values to set android.control.aeMode, 2574 android.control.awbMode, and android.control.afMode when using a scene 2575 mode other than FACE_PRIORITY and FACE_PRIORITY_LOW_LIGHT (if supported). 2576 </hal_details> 2577 <tag id="BC" /> 2578 </entry> 2579 </static> 2580 <dynamic> 2581 <entry name="aePrecaptureId" type="int32" visibility="system" deprecated="true"> 2582 <description>The ID sent with the latest 2583 CAMERA2_TRIGGER_PRECAPTURE_METERING call</description> 2584 <deprecation_description> 2585 Removed in camera HAL v3 2586 </deprecation_description> 2587 <details>Must be 0 if no 2588 CAMERA2_TRIGGER_PRECAPTURE_METERING trigger received yet 2589 by HAL. Always updated even if AE algorithm ignores the 2590 trigger</details> 2591 </entry> 2592 <clone entry="android.control.aeAntibandingMode" kind="controls"> 2593 </clone> 2594 <clone entry="android.control.aeExposureCompensation" kind="controls"> 2595 </clone> 2596 <clone entry="android.control.aeLock" kind="controls"> 2597 </clone> 2598 <clone entry="android.control.aeMode" kind="controls"> 2599 </clone> 2600 <clone entry="android.control.aeRegions" kind="controls"> 2601 </clone> 2602 <clone entry="android.control.aeTargetFpsRange" kind="controls"> 2603 </clone> 2604 <clone entry="android.control.aePrecaptureTrigger" kind="controls"> 2605 </clone> 2606 <entry name="aeState" type="byte" visibility="public" enum="true" 2607 hwlevel="limited"> 2608 <enum> 2609 <value>INACTIVE 2610 <notes>AE is off or recently reset. 2611 2612 When a camera device is opened, it starts in 2613 this state. This is a transient state, the camera device may skip reporting 2614 this state in capture result.</notes></value> 2615 <value>SEARCHING 2616 <notes>AE doesn't yet have a good set of control values 2617 for the current scene. 2618 2619 This is a transient state, the camera device may skip 2620 reporting this state in capture result.</notes></value> 2621 <value>CONVERGED 2622 <notes>AE has a good set of control values for the 2623 current scene.</notes></value> 2624 <value>LOCKED 2625 <notes>AE has been locked.</notes></value> 2626 <value>FLASH_REQUIRED 2627 <notes>AE has a good set of control values, but flash 2628 needs to be fired for good quality still 2629 capture.</notes></value> 2630 <value>PRECAPTURE 2631 <notes>AE has been asked to do a precapture sequence 2632 and is currently executing it. 2633 2634 Precapture can be triggered through setting 2635 android.control.aePrecaptureTrigger to START. Currently 2636 active and completed (if it causes camera device internal AE lock) precapture 2637 metering sequence can be canceled through setting 2638 android.control.aePrecaptureTrigger to CANCEL. 2639 2640 Once PRECAPTURE completes, AE will transition to CONVERGED 2641 or FLASH_REQUIRED as appropriate. This is a transient 2642 state, the camera device may skip reporting this state in 2643 capture result.</notes></value> 2644 </enum> 2645 <description>Current state of the auto-exposure (AE) algorithm.</description> 2646 <details>Switching between or enabling AE modes (android.control.aeMode) always 2647 resets the AE state to INACTIVE. Similarly, switching between android.control.mode, 2648 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2649 the algorithm states to INACTIVE. 2650 2651 The camera device can do several state transitions between two results, if it is 2652 allowed by the state transition table. For example: INACTIVE may never actually be 2653 seen in a result. 2654 2655 The state in the result is the state for this image (in sync with this image): if 2656 AE state becomes CONVERGED, then the image data associated with this result should 2657 be good to use. 2658 2659 Below are state transition tables for different AE modes. 2660 2661 State | Transition Cause | New State | Notes 2662 :------------:|:----------------:|:---------:|:-----------------------: 2663 INACTIVE | | INACTIVE | Camera device auto exposure algorithm is disabled 2664 2665 When android.control.aeMode is AE_MODE_ON*: 2666 2667 State | Transition Cause | New State | Notes 2668 :-------------:|:--------------------------------------------:|:--------------:|:-----------------: 2669 INACTIVE | Camera device initiates AE scan | SEARCHING | Values changing 2670 INACTIVE | android.control.aeLock is ON | LOCKED | Values locked 2671 SEARCHING | Camera device finishes AE scan | CONVERGED | Good values, not changing 2672 SEARCHING | Camera device finishes AE scan | FLASH_REQUIRED | Converged but too dark w/o flash 2673 SEARCHING | android.control.aeLock is ON | LOCKED | Values locked 2674 CONVERGED | Camera device initiates AE scan | SEARCHING | Values changing 2675 CONVERGED | android.control.aeLock is ON | LOCKED | Values locked 2676 FLASH_REQUIRED | Camera device initiates AE scan | SEARCHING | Values changing 2677 FLASH_REQUIRED | android.control.aeLock is ON | LOCKED | Values locked 2678 LOCKED | android.control.aeLock is OFF | SEARCHING | Values not good after unlock 2679 LOCKED | android.control.aeLock is OFF | CONVERGED | Values good after unlock 2680 LOCKED | android.control.aeLock is OFF | FLASH_REQUIRED | Exposure good, but too dark 2681 PRECAPTURE | Sequence done. android.control.aeLock is OFF | CONVERGED | Ready for high-quality capture 2682 PRECAPTURE | Sequence done. android.control.aeLock is ON | LOCKED | Ready for high-quality capture 2683 LOCKED | aeLock is ON and aePrecaptureTrigger is START | LOCKED | Precapture trigger is ignored when AE is already locked 2684 LOCKED | aeLock is ON and aePrecaptureTrigger is CANCEL| LOCKED | Precapture trigger is ignored when AE is already locked 2685 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is START | PRECAPTURE | Start AE precapture metering sequence 2686 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is CANCEL| INACTIVE | Currently active precapture metering sequence is canceled 2687 2688 If the camera device supports AE external flash mode (ON_EXTERNAL_FLASH is included in 2689 android.control.aeAvailableModes), android.control.aeState must be FLASH_REQUIRED after 2690 the camera device finishes AE scan and it's too dark without flash. 2691 2692 For the above table, the camera device may skip reporting any state changes that happen 2693 without application intervention (i.e. mode switch, trigger, locking). Any state that 2694 can be skipped in that manner is called a transient state. 2695 2696 For example, for above AE modes (AE_MODE_ON*), in addition to the state transitions 2697 listed in above table, it is also legal for the camera device to skip one or more 2698 transient states between two results. See below table for examples: 2699 2700 State | Transition Cause | New State | Notes 2701 :-------------:|:-----------------------------------------------------------:|:--------------:|:-----------------: 2702 INACTIVE | Camera device finished AE scan | CONVERGED | Values are already good, transient states are skipped by camera device. 2703 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. 2704 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is START, sequence done | CONVERGED | Converged after a precapture sequence, transient states are skipped by camera device. 2705 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. 2706 Any state (excluding LOCKED) | android.control.aePrecaptureTrigger is CANCEL, converged | CONVERGED | Converged after a precapture sequences canceled, transient states are skipped by camera device. 2707 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. 2708 FLASH_REQUIRED | Camera device finished AE scan | CONVERGED | Converged after a new scan, transient states are skipped by camera device. 2709 </details> 2710 </entry> 2711 <clone entry="android.control.afMode" kind="controls"> 2712 </clone> 2713 <clone entry="android.control.afRegions" kind="controls"> 2714 </clone> 2715 <clone entry="android.control.afTrigger" kind="controls"> 2716 </clone> 2717 <entry name="afState" type="byte" visibility="public" enum="true" 2718 hwlevel="legacy"> 2719 <enum> 2720 <value>INACTIVE 2721 <notes>AF is off or has not yet tried to scan/been asked 2722 to scan. 2723 2724 When a camera device is opened, it starts in this 2725 state. This is a transient state, the camera device may 2726 skip reporting this state in capture 2727 result.</notes></value> 2728 <value>PASSIVE_SCAN 2729 <notes>AF is currently performing an AF scan initiated the 2730 camera device in a continuous autofocus mode. 2731 2732 Only used by CONTINUOUS_* AF modes. This is a transient 2733 state, the camera device may skip reporting this state in 2734 capture result.</notes></value> 2735 <value>PASSIVE_FOCUSED 2736 <notes>AF currently believes it is in focus, but may 2737 restart scanning at any time. 2738 2739 Only used by CONTINUOUS_* AF modes. This is a transient 2740 state, the camera device may skip reporting this state in 2741 capture result.</notes></value> 2742 <value>ACTIVE_SCAN 2743 <notes>AF is performing an AF scan because it was 2744 triggered by AF trigger. 2745 2746 Only used by AUTO or MACRO AF modes. This is a transient 2747 state, the camera device may skip reporting this state in 2748 capture result.</notes></value> 2749 <value>FOCUSED_LOCKED 2750 <notes>AF believes it is focused correctly and has locked 2751 focus. 2752 2753 This state is reached only after an explicit START AF trigger has been 2754 sent (android.control.afTrigger), when good focus has been obtained. 2755 2756 The lens will remain stationary until the AF mode (android.control.afMode) is changed or 2757 a new AF trigger is sent to the camera device (android.control.afTrigger). 2758 </notes></value> 2759 <value>NOT_FOCUSED_LOCKED 2760 <notes>AF has failed to focus successfully and has locked 2761 focus. 2762 2763 This state is reached only after an explicit START AF trigger has been 2764 sent (android.control.afTrigger), when good focus cannot be obtained. 2765 2766 The lens will remain stationary until the AF mode (android.control.afMode) is changed or 2767 a new AF trigger is sent to the camera device (android.control.afTrigger). 2768 </notes></value> 2769 <value>PASSIVE_UNFOCUSED 2770 <notes>AF finished a passive scan without finding focus, 2771 and may restart scanning at any time. 2772 2773 Only used by CONTINUOUS_* AF modes. This is a transient state, the camera 2774 device may skip reporting this state in capture result. 2775 2776 LEGACY camera devices do not support this state. When a passive 2777 scan has finished, it will always go to PASSIVE_FOCUSED. 2778 </notes></value> 2779 </enum> 2780 <description>Current state of auto-focus (AF) algorithm.</description> 2781 <details> 2782 Switching between or enabling AF modes (android.control.afMode) always 2783 resets the AF state to INACTIVE. Similarly, switching between android.control.mode, 2784 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2785 the algorithm states to INACTIVE. 2786 2787 The camera device can do several state transitions between two results, if it is 2788 allowed by the state transition table. For example: INACTIVE may never actually be 2789 seen in a result. 2790 2791 The state in the result is the state for this image (in sync with this image): if 2792 AF state becomes FOCUSED, then the image data associated with this result should 2793 be sharp. 2794 2795 Below are state transition tables for different AF modes. 2796 2797 When android.control.afMode is AF_MODE_OFF or AF_MODE_EDOF: 2798 2799 State | Transition Cause | New State | Notes 2800 :------------:|:----------------:|:---------:|:-----------: 2801 INACTIVE | | INACTIVE | Never changes 2802 2803 When android.control.afMode is AF_MODE_AUTO or AF_MODE_MACRO: 2804 2805 State | Transition Cause | New State | Notes 2806 :-----------------:|:----------------:|:------------------:|:--------------: 2807 INACTIVE | AF_TRIGGER | ACTIVE_SCAN | Start AF sweep, Lens now moving 2808 ACTIVE_SCAN | AF sweep done | FOCUSED_LOCKED | Focused, Lens now locked 2809 ACTIVE_SCAN | AF sweep done | NOT_FOCUSED_LOCKED | Not focused, Lens now locked 2810 ACTIVE_SCAN | AF_CANCEL | INACTIVE | Cancel/reset AF, Lens now locked 2811 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF 2812 FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving 2813 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF 2814 NOT_FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving 2815 Any state | Mode change | INACTIVE | 2816 2817 For the above table, the camera device may skip reporting any state changes that happen 2818 without application intervention (i.e. mode switch, trigger, locking). Any state that 2819 can be skipped in that manner is called a transient state. 2820 2821 For example, for these AF modes (AF_MODE_AUTO and AF_MODE_MACRO), in addition to the 2822 state transitions listed in above table, it is also legal for the camera device to skip 2823 one or more transient states between two results. See below table for examples: 2824 2825 State | Transition Cause | New State | Notes 2826 :-----------------:|:----------------:|:------------------:|:--------------: 2827 INACTIVE | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. 2828 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | Focus failed after a scan, lens is now locked. 2829 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. 2830 NOT_FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is good after a scan, lens is not locked. 2831 2832 2833 When android.control.afMode is AF_MODE_CONTINUOUS_VIDEO: 2834 2835 State | Transition Cause | New State | Notes 2836 :-----------------:|:-----------------------------------:|:------------------:|:--------------: 2837 INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2838 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked 2839 PASSIVE_SCAN | Camera device completes current scan| PASSIVE_FOCUSED | End AF scan, Lens now locked 2840 PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, Lens now locked 2841 PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Immediate transition, if focus is good. Lens now locked 2842 PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate transition, if focus is bad. Lens now locked 2843 PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens position, Lens now locked 2844 PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2845 PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2846 PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate transition, lens now locked 2847 PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate transition, lens now locked 2848 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect 2849 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2850 NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect 2851 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2852 2853 When android.control.afMode is AF_MODE_CONTINUOUS_PICTURE: 2854 2855 State | Transition Cause | New State | Notes 2856 :-----------------:|:------------------------------------:|:------------------:|:--------------: 2857 INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2858 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked 2859 PASSIVE_SCAN | Camera device completes current scan | PASSIVE_FOCUSED | End AF scan, Lens now locked 2860 PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, Lens now locked 2861 PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Eventual transition once the focus is good. Lens now locked 2862 PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Eventual transition if cannot find focus. Lens now locked 2863 PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens position, Lens now locked 2864 PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2865 PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2866 PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. Lens now locked 2867 PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. Lens now locked 2868 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect 2869 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2870 NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect 2871 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2872 2873 When switch between AF_MODE_CONTINUOUS_* (CAF modes) and AF_MODE_AUTO/AF_MODE_MACRO 2874 (AUTO modes), the initial INACTIVE or PASSIVE_SCAN states may be skipped by the 2875 camera device. When a trigger is included in a mode switch request, the trigger 2876 will be evaluated in the context of the new mode in the request. 2877 See below table for examples: 2878 2879 State | Transition Cause | New State | Notes 2880 :-----------:|:--------------------------------------:|:----------------------------------------:|:--------------: 2881 any state | CAF-->AUTO mode switch | INACTIVE | Mode switch without trigger, initial state must be INACTIVE 2882 any state | CAF-->AUTO mode switch with AF_TRIGGER | trigger-reachable states from INACTIVE | Mode switch with trigger, INACTIVE is skipped 2883 any state | AUTO-->CAF mode switch | passively reachable states from INACTIVE | Mode switch without trigger, passive transient state is skipped 2884 </details> 2885 </entry> 2886 <entry name="afTriggerId" type="int32" visibility="system" deprecated="true"> 2887 <description>The ID sent with the latest 2888 CAMERA2_TRIGGER_AUTOFOCUS call</description> 2889 <deprecation_description> 2890 Removed in camera HAL v3 2891 </deprecation_description> 2892 <details>Must be 0 if no CAMERA2_TRIGGER_AUTOFOCUS trigger 2893 received yet by HAL. Always updated even if AF algorithm 2894 ignores the trigger</details> 2895 </entry> 2896 <clone entry="android.control.awbLock" kind="controls"> 2897 </clone> 2898 <clone entry="android.control.awbMode" kind="controls"> 2899 </clone> 2900 <clone entry="android.control.awbRegions" kind="controls"> 2901 </clone> 2902 <clone entry="android.control.captureIntent" kind="controls"> 2903 </clone> 2904 <entry name="awbState" type="byte" visibility="public" enum="true" 2905 hwlevel="limited"> 2906 <enum> 2907 <value>INACTIVE 2908 <notes>AWB is not in auto mode, or has not yet started metering. 2909 2910 When a camera device is opened, it starts in this 2911 state. This is a transient state, the camera device may 2912 skip reporting this state in capture 2913 result.</notes></value> 2914 <value>SEARCHING 2915 <notes>AWB doesn't yet have a good set of control 2916 values for the current scene. 2917 2918 This is a transient state, the camera device 2919 may skip reporting this state in capture result.</notes></value> 2920 <value>CONVERGED 2921 <notes>AWB has a good set of control values for the 2922 current scene.</notes></value> 2923 <value>LOCKED 2924 <notes>AWB has been locked. 2925 </notes></value> 2926 </enum> 2927 <description>Current state of auto-white balance (AWB) algorithm.</description> 2928 <details>Switching between or enabling AWB modes (android.control.awbMode) always 2929 resets the AWB state to INACTIVE. Similarly, switching between android.control.mode, 2930 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2931 the algorithm states to INACTIVE. 2932 2933 The camera device can do several state transitions between two results, if it is 2934 allowed by the state transition table. So INACTIVE may never actually be seen in 2935 a result. 2936 2937 The state in the result is the state for this image (in sync with this image): if 2938 AWB state becomes CONVERGED, then the image data associated with this result should 2939 be good to use. 2940 2941 Below are state transition tables for different AWB modes. 2942 2943 When `android.control.awbMode != AWB_MODE_AUTO`: 2944 2945 State | Transition Cause | New State | Notes 2946 :------------:|:----------------:|:---------:|:-----------------------: 2947 INACTIVE | |INACTIVE |Camera device auto white balance algorithm is disabled 2948 2949 When android.control.awbMode is AWB_MODE_AUTO: 2950 2951 State | Transition Cause | New State | Notes 2952 :-------------:|:--------------------------------:|:-------------:|:-----------------: 2953 INACTIVE | Camera device initiates AWB scan | SEARCHING | Values changing 2954 INACTIVE | android.control.awbLock is ON | LOCKED | Values locked 2955 SEARCHING | Camera device finishes AWB scan | CONVERGED | Good values, not changing 2956 SEARCHING | android.control.awbLock is ON | LOCKED | Values locked 2957 CONVERGED | Camera device initiates AWB scan | SEARCHING | Values changing 2958 CONVERGED | android.control.awbLock is ON | LOCKED | Values locked 2959 LOCKED | android.control.awbLock is OFF | SEARCHING | Values not good after unlock 2960 2961 For the above table, the camera device may skip reporting any state changes that happen 2962 without application intervention (i.e. mode switch, trigger, locking). Any state that 2963 can be skipped in that manner is called a transient state. 2964 2965 For example, for this AWB mode (AWB_MODE_AUTO), in addition to the state transitions 2966 listed in above table, it is also legal for the camera device to skip one or more 2967 transient states between two results. See below table for examples: 2968 2969 State | Transition Cause | New State | Notes 2970 :-------------:|:--------------------------------:|:-------------:|:-----------------: 2971 INACTIVE | Camera device finished AWB scan | CONVERGED | Values are already good, transient states are skipped by camera device. 2972 LOCKED | android.control.awbLock is OFF | CONVERGED | Values good after unlock, transient states are skipped by camera device. 2973 </details> 2974 </entry> 2975 <clone entry="android.control.effectMode" kind="controls"> 2976 </clone> 2977 <clone entry="android.control.mode" kind="controls"> 2978 </clone> 2979 <clone entry="android.control.sceneMode" kind="controls"> 2980 </clone> 2981 <clone entry="android.control.videoStabilizationMode" kind="controls"> 2982 </clone> 2983 </dynamic> 2984 <static> 2985 <entry name="availableHighSpeedVideoConfigurations" type="int32" visibility="hidden" 2986 container="array" typedef="highSpeedVideoConfiguration" hwlevel="limited"> 2987 <array> 2988 <size>5</size> 2989 <size>n</size> 2990 </array> 2991 <description> 2992 List of available high speed video size, fps range and max batch size configurations 2993 supported by the camera device, in the format of (width, height, fps_min, fps_max, batch_size_max). 2994 </description> 2995 <range> 2996 For each configuration, the fps_max &gt;= 120fps. 2997 </range> 2998 <details> 2999 When CONSTRAINED_HIGH_SPEED_VIDEO is supported in android.request.availableCapabilities, 3000 this metadata will list the supported high speed video size, fps range and max batch size 3001 configurations. All the sizes listed in this configuration will be a subset of the sizes 3002 reported by {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} 3003 for processed non-stalling formats. 3004 3005 For the high speed video use case, the application must 3006 select the video size and fps range from this metadata to configure the recording and 3007 preview streams and setup the recording requests. For example, if the application intends 3008 to do high speed recording, it can select the maximum size reported by this metadata to 3009 configure output streams. Once the size is selected, application can filter this metadata 3010 by selected size and get the supported fps ranges, and use these fps ranges to setup the 3011 recording requests. Note that for the use case of multiple output streams, application 3012 must select one unique size from this metadata to use (e.g., preview and recording streams 3013 must have the same size). Otherwise, the high speed capture session creation will fail. 3014 3015 The min and max fps will be multiple times of 30fps. 3016 3017 High speed video streaming extends significant performance pressure to camera hardware, 3018 to achieve efficient high speed streaming, the camera device may have to aggregate 3019 multiple frames together and send to camera device for processing where the request 3020 controls are same for all the frames in this batch. Max batch size indicates 3021 the max possible number of frames the camera device will group together for this high 3022 speed stream configuration. This max batch size will be used to generate a high speed 3023 recording request list by 3024 {@link android.hardware.camera2.CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList}. 3025 The max batch size for each configuration will satisfy below conditions: 3026 3027 * Each max batch size will be a divisor of its corresponding fps_max / 30. For example, 3028 if max_fps is 300, max batch size will only be 1, 2, 5, or 10. 3029 * The camera device may choose smaller internal batch size for each configuration, but 3030 the actual batch size will be a divisor of max batch size. For example, if the max batch 3031 size is 8, the actual batch size used by camera device will only be 1, 2, 4, or 8. 3032 * The max batch size in each configuration entry must be no larger than 32. 3033 3034 The camera device doesn't have to support batch mode to achieve high speed video recording, 3035 in such case, batch_size_max will be reported as 1 in each configuration entry. 3036 3037 This fps ranges in this configuration list can only be used to create requests 3038 that are submitted to a high speed camera capture session created by 3039 {@link android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}. 3040 The fps ranges reported in this metadata must not be used to setup capture requests for 3041 normal capture session, or it will cause request error. 3042 </details> 3043 <hal_details> 3044 All the sizes listed in this configuration will be a subset of the sizes reported by 3045 android.scaler.availableStreamConfigurations for processed non-stalling output formats. 3046 Note that for all high speed video configurations, HAL must be able to support a minimum 3047 of two streams, though the application might choose to configure just one stream. 3048 3049 The HAL may support multiple sensor modes for high speed outputs, for example, 120fps 3050 sensor mode and 120fps recording, 240fps sensor mode for 240fps recording. The application 3051 usually starts preview first, then starts recording. To avoid sensor mode switch caused 3052 stutter when starting recording as much as possible, the application may want to ensure 3053 the same sensor mode is used for preview and recording. Therefore, The HAL must advertise 3054 the variable fps range [30, fps_max] for each fixed fps range in this configuration list. 3055 For example, if the HAL advertises [120, 120] and [240, 240], the HAL must also advertise 3056 [30, 120] and [30, 240] for each configuration. In doing so, if the application intends to 3057 do 120fps recording, it can select [30, 120] to start preview, and [120, 120] to start 3058 recording. For these variable fps ranges, it's up to the HAL to decide the actual fps 3059 values that are suitable for smooth preview streaming. 3060 If the HAL sees different max_fps values that fall into different sensor modes in a 3061 sequence of requests, the HAL must switch the sensor mode as quick as possible to minimize 3062 the mode switch caused stutter. 3063 3064 HAL can also support 60fps preview during high speed recording session by advertising 3065 [60, max_fps] for preview and [max_fps, max_fps] for recording. However, HAL must not 3066 advertise both 30fps preview and 60fps preview for the same recording frame rate. 3067 3068 Starting from AIDL ICameraDevice V2, camera HAL must report the valid batch_size_max. The 3069 field will actually be used to generate a high speed recording request list. 3070 </hal_details> 3071 <tag id="V1" /> 3072 </entry> 3073 <entry name="aeLockAvailable" type="byte" visibility="public" enum="true" 3074 typedef="boolean" hwlevel="legacy"> 3075 <enum> 3076 <value>FALSE</value> 3077 <value>TRUE</value> 3078 </enum> 3079 <description>Whether the camera device supports android.control.aeLock</description> 3080 <details> 3081 Devices with MANUAL_SENSOR capability or BURST_CAPTURE capability will always 3082 list `true`. This includes FULL devices. 3083 </details> 3084 <tag id="BC"/> 3085 </entry> 3086 <entry name="awbLockAvailable" type="byte" visibility="public" enum="true" 3087 typedef="boolean" hwlevel="legacy"> 3088 <enum> 3089 <value>FALSE</value> 3090 <value>TRUE</value> 3091 </enum> 3092 <description>Whether the camera device supports android.control.awbLock</description> 3093 <details> 3094 Devices with MANUAL_POST_PROCESSING capability or BURST_CAPTURE capability will 3095 always list `true`. This includes FULL devices. 3096 </details> 3097 <tag id="BC"/> 3098 </entry> 3099 <entry name="availableModes" type="byte" visibility="public" 3100 type_notes="List of enums (android.control.mode)." container="array" 3101 typedef="enumList" hwlevel="legacy"> 3102 <array> 3103 <size>n</size> 3104 </array> 3105 <description> 3106 List of control modes for android.control.mode that are supported by this camera 3107 device. 3108 </description> 3109 <range>Any value listed in android.control.mode</range> 3110 <details> 3111 This list contains control modes that can be set for the camera device. 3112 LEGACY mode devices will always support AUTO mode. LIMITED and FULL 3113 devices will always support OFF, AUTO modes. 3114 </details> 3115 </entry> 3116 <entry name="postRawSensitivityBoostRange" type="int32" visibility="public" 3117 type_notes="Range of supported post RAW sensitivity boosts" 3118 container="array" typedef="rangeInt"> 3119 <array> 3120 <size>2</size> 3121 </array> 3122 <description>Range of boosts for android.control.postRawSensitivityBoost supported 3123 by this camera device. 3124 </description> 3125 <units>ISO arithmetic units, the same as android.sensor.sensitivity</units> 3126 <details> 3127 Devices support post RAW sensitivity boost will advertise 3128 android.control.postRawSensitivityBoost key for controlling 3129 post RAW sensitivity boost. 3130 3131 This key will be `null` for devices that do not support any RAW format 3132 outputs. For devices that do support RAW format outputs, this key will always 3133 present, and if a device does not support post RAW sensitivity boost, it will 3134 list `(100, 100)` in this key. 3135 </details> 3136 <hal_details> 3137 This key is added in legacy HAL3.4. For legacy HAL3.3 or earlier devices, camera 3138 framework will generate this key as `(100, 100)` if device supports any of RAW output 3139 formats. All legacy HAL3.4 and above devices should list this key if device supports 3140 any of RAW output formats. 3141 </hal_details> 3142 </entry> 3143 </static> 3144 <controls> 3145 <entry name="postRawSensitivityBoost" type="int32" visibility="public"> 3146 <description>The amount of additional sensitivity boost applied to output images 3147 after RAW sensor data is captured. 3148 </description> 3149 <units>ISO arithmetic units, the same as android.sensor.sensitivity</units> 3150 <range>android.control.postRawSensitivityBoostRange</range> 3151 <details> 3152 Some camera devices support additional digital sensitivity boosting in the 3153 camera processing pipeline after sensor RAW image is captured. 3154 Such a boost will be applied to YUV/JPEG format output images but will not 3155 have effect on RAW output formats like RAW_SENSOR, RAW10, RAW12 or RAW_OPAQUE. 3156 3157 This key will be `null` for devices that do not support any RAW format 3158 outputs. For devices that do support RAW format outputs, this key will always 3159 present, and if a device does not support post RAW sensitivity boost, it will 3160 list `100` in this key. 3161 3162 If the camera device cannot apply the exact boost requested, it will reduce the 3163 boost to the nearest supported value. 3164 The final boost value used will be available in the output capture result. 3165 3166 For devices that support post RAW sensitivity boost, the YUV/JPEG output images 3167 of such device will have the total sensitivity of 3168 `android.sensor.sensitivity * android.control.postRawSensitivityBoost / 100` 3169 The sensitivity of RAW format images will always be `android.sensor.sensitivity` 3170 3171 This control is only effective if android.control.aeMode or android.control.mode is set to 3172 OFF; otherwise the auto-exposure algorithm will override this value. 3173 </details> 3174 </entry> 3175 </controls> 3176 <dynamic> 3177 <clone entry="android.control.postRawSensitivityBoost" kind="controls"> 3178 </clone> 3179 </dynamic> 3180 <controls> 3181 <entry name="enableZsl" type="byte" visibility="public" enum="true" typedef="boolean"> 3182 <enum> 3183 <value>FALSE 3184 <notes>Requests with android.control.captureIntent == STILL_CAPTURE must be captured 3185 after previous requests.</notes></value> 3186 <value>TRUE 3187 <notes>Requests with android.control.captureIntent == STILL_CAPTURE may or may not be 3188 captured before previous requests.</notes></value> 3189 </enum> 3190 <description>Allow camera device to enable zero-shutter-lag mode for requests with 3191 android.control.captureIntent == STILL_CAPTURE. 3192 </description> 3193 <details> 3194 If enableZsl is `true`, the camera device may enable zero-shutter-lag mode for requests with 3195 STILL_CAPTURE capture intent. The camera device may use images captured in the past to 3196 produce output images for a zero-shutter-lag request. The result metadata including the 3197 android.sensor.timestamp reflects the source frames used to produce output images. 3198 Therefore, the contents of the output images and the result metadata may be out of order 3199 compared to previous regular requests. enableZsl does not affect requests with other 3200 capture intents. 3201 3202 For example, when requests are submitted in the following order: 3203 Request A: enableZsl is ON, android.control.captureIntent is PREVIEW 3204 Request B: enableZsl is ON, android.control.captureIntent is STILL_CAPTURE 3205 3206 The output images for request B may have contents captured before the output images for 3207 request A, and the result metadata for request B may be older than the result metadata for 3208 request A. 3209 3210 Note that when enableZsl is `true`, it is not guaranteed to get output images captured in 3211 the past for requests with STILL_CAPTURE capture intent. 3212 3213 For applications targeting SDK versions O and newer, the value of enableZsl in 3214 TEMPLATE_STILL_CAPTURE template may be `true`. The value in other templates is always 3215 `false` if present. 3216 3217 For applications targeting SDK versions older than O, the value of enableZsl in all 3218 capture templates is always `false` if present. 3219 3220 For application-operated ZSL, use CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template. 3221 </details> 3222 <hal_details> 3223 It is valid for HAL to produce regular output images for requests with STILL_CAPTURE 3224 capture intent. 3225 </hal_details> 3226 </entry> 3227 </controls> 3228 <dynamic> 3229 <clone entry="android.control.enableZsl" kind="controls"> 3230 </clone> 3231 <entry name="afSceneChange" type="byte" visibility="public" enum="true" hal_version="3.3"> 3232 <enum> 3233 <value>NOT_DETECTED 3234 <notes>Scene change is not detected within the AF region(s).</notes></value> 3235 <value>DETECTED 3236 <notes>Scene change is detected within the AF region(s).</notes></value> 3237 </enum> 3238 <description>Whether a significant scene change is detected within the currently-set AF 3239 region(s).</description> 3240 <details>When the camera focus routine detects a change in the scene it is looking at, 3241 such as a large shift in camera viewpoint, significant motion in the scene, or a 3242 significant illumination change, this value will be set to DETECTED for a single capture 3243 result. Otherwise the value will be NOT_DETECTED. The threshold for detection is similar 3244 to what would trigger a new passive focus scan to begin in CONTINUOUS autofocus modes. 3245 3246 This key will be available if the camera device advertises this key via {@link 3247 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 3248 </details> 3249 </entry> 3250 </dynamic> 3251 <static> 3252 <entry name="availableExtendedSceneModeMaxSizes" type="int32" 3253 visibility="ndk_public" optional="true" 3254 type_notes="List of extended scene modes and the corresponding max streaming sizes." 3255 container="array" hwlevel="limited" hal_version="3.5"> 3256 <array> 3257 <size>3</size> 3258 <size>n</size> 3259 </array> 3260 <description> 3261 The list of extended scene modes for android.control.extendedSceneMode that are supported 3262 by this camera device, and each extended scene mode's maximum streaming (non-stall) size 3263 with effect. 3264 </description> 3265 <units>(mode, width, height)</units> 3266 <details> 3267 For DISABLED mode, the camera behaves normally with no extended scene mode enabled. 3268 3269 For BOKEH_STILL_CAPTURE mode, the maximum streaming dimension specifies the limit 3270 under which bokeh is effective when capture intent is PREVIEW. Note that when capture 3271 intent is PREVIEW, the bokeh effect may not be as high in quality compared to 3272 STILL_CAPTURE intent in order to maintain reasonable frame rate. The maximum streaming 3273 dimension must be one of the YUV_420_888 or PRIVATE resolutions in 3274 availableStreamConfigurations, or (0, 0) if preview bokeh is not supported. If the 3275 application configures a stream larger than the maximum streaming dimension, bokeh 3276 effect may not be applied for this stream for PREVIEW intent. 3277 3278 For BOKEH_CONTINUOUS mode, the maximum streaming dimension specifies the limit under 3279 which bokeh is effective. This dimension must be one of the YUV_420_888 or PRIVATE 3280 resolutions in availableStreamConfigurations, and if the sensor maximum resolution is 3281 larger than or equal to 1080p, the maximum streaming dimension must be at least 1080p. 3282 If the application configures a stream with larger dimension, the stream may not have 3283 bokeh effect applied. 3284 </details> 3285 <hal_details> 3286 For available extended scene modes, DISABLED will always be listed. 3287 3288 HAL must support at list one non-OFF extended scene mode if extendedSceneMode control is 3289 available on the camera device. For DISABLED mode, the maximum streaming resolution must 3290 be set to (0, 0). 3291 </hal_details> 3292 </entry> 3293 <entry name="availableExtendedSceneModeZoomRatioRanges" type="float" 3294 visibility="ndk_public" optional="true" 3295 type_notes="Zoom ranges for all supported non-OFF extended scene modes." 3296 container="array" hwlevel="limited" hal_version="3.5"> 3297 <array> 3298 <size>2</size> 3299 <size>n</size> 3300 </array> 3301 <description> 3302 The ranges of supported zoom ratio for non-DISABLED android.control.extendedSceneMode. 3303 </description> 3304 <units>(minZoom, maxZoom)</units> 3305 <details> 3306 When extended scene mode is set, the camera device may have limited range of zoom ratios 3307 compared to when extended scene mode is DISABLED. This tag lists the zoom ratio ranges 3308 for all supported non-DISABLED extended scene modes, in the same order as in 3309 android.control.availableExtended. 3310 3311 Range [1.0, 1.0] means that no zoom (optical or digital) is supported. 3312 </details> 3313 </entry> 3314 <entry name="availableExtendedSceneModeCapabilities" type="int32" visibility="public" 3315 synthetic="true" container="array" typedef="capability" hal_version="3.5"> 3316 <array> 3317 <size>n</size> 3318 </array> 3319 <description>The list of extended scene modes for android.control.extendedSceneMode that 3320 are supported by this camera device, and each extended scene mode's capabilities such 3321 as maximum streaming size, and supported zoom ratio ranges.</description> 3322 <details> 3323 For DISABLED mode, the camera behaves normally with no extended scene mode enabled. 3324 3325 For BOKEH_STILL_CAPTURE mode, the maximum streaming dimension specifies the limit 3326 under which bokeh is effective when capture intent is PREVIEW. Note that when capture 3327 intent is PREVIEW, the bokeh effect may not be as high quality compared to STILL_CAPTURE 3328 intent in order to maintain reasonable frame rate. The maximum streaming dimension must 3329 be one of the YUV_420_888 or PRIVATE resolutions in availableStreamConfigurations, or 3330 (0, 0) if preview bokeh is not supported. If the application configures a stream 3331 larger than the maximum streaming dimension, bokeh effect may not be applied for this 3332 stream for PREVIEW intent. 3333 3334 For BOKEH_CONTINUOUS mode, the maximum streaming dimension specifies the limit under 3335 which bokeh is effective. This dimension must be one of the YUV_420_888 or PRIVATE 3336 resolutions in availableStreamConfigurations, and if the sensor maximum resolution is 3337 larger than or equal to 1080p, the maximum streaming dimension must be at least 1080p. 3338 If the application configures a stream with larger dimension, the stream may not have 3339 bokeh effect applied. 3340 3341 When extended scene mode is set, the camera device may have limited range of zoom ratios 3342 compared to when the mode is DISABLED. availableExtendedSceneModeCapabilities lists the 3343 zoom ranges for all supported extended modes. A range of (1.0, 1.0) means that no zoom 3344 (optical or digital) is supported. 3345 </details> 3346 </entry> 3347 </static> 3348 <controls> 3349 <entry name="extendedSceneMode" type="byte" visibility="public" optional="true" 3350 enum="true" hal_version="3.5"> 3351 <enum> 3352 <value id="0">DISABLED 3353 <notes>Extended scene mode is disabled.</notes></value> 3354 <value>BOKEH_STILL_CAPTURE 3355 <notes>High quality bokeh mode is enabled for all non-raw streams (including YUV, 3356 JPEG, and IMPLEMENTATION_DEFINED) when capture intent is STILL_CAPTURE. Due to the 3357 extra image processing, this mode may introduce additional stall to non-raw streams. 3358 This mode should be used in high quality still capture use case. 3359 </notes> 3360 </value> 3361 <value>BOKEH_CONTINUOUS 3362 <notes>Bokeh effect must not slow down capture rate relative to sensor raw output, 3363 and the effect is applied to all processed streams no larger than the maximum 3364 streaming dimension. This mode should be used if performance and power are a 3365 priority, such as video recording. 3366 </notes> 3367 </value> 3368 <value visibility="hidden" id="0x40">VENDOR_START 3369 <notes> 3370 Vendor defined extended scene modes. These depend on vendor implementation. 3371 </notes> 3372 </value> 3373 </enum> 3374 <description>Whether extended scene mode is enabled for a particular capture request. 3375 </description> 3376 <details> 3377 With bokeh mode, the camera device may blur out the parts of scene that are not in 3378 focus, creating a bokeh (or shallow depth of field) effect for people or objects. 3379 3380 When set to BOKEH_STILL_CAPTURE mode with STILL_CAPTURE capture intent, due to the extra 3381 processing needed for high quality bokeh effect, the stall may be longer than when 3382 capture intent is not STILL_CAPTURE. 3383 3384 When set to BOKEH_STILL_CAPTURE mode with PREVIEW capture intent, 3385 3386 * If the camera device has BURST_CAPTURE capability, the frame rate requirement of 3387 BURST_CAPTURE must still be met. 3388 * All streams not larger than the maximum streaming dimension for BOKEH_STILL_CAPTURE mode 3389 (queried via {@link android.hardware.camera2.CameraCharacteristics#CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_CAPABILITIES|ACAMERA_CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_MAX_SIZES}) 3390 will have preview bokeh effect applied. 3391 3392 When set to BOKEH_CONTINUOUS mode, configured streams dimension should not exceed this mode's 3393 maximum streaming dimension in order to have bokeh effect applied. Bokeh effect may not 3394 be available for streams larger than the maximum streaming dimension. 3395 3396 Switching between different extended scene modes may involve reconfiguration of the camera 3397 pipeline, resulting in long latency. The application should check this key against the 3398 available session keys queried via 3399 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys|ACameraManager_getCameraCharacteristics}. 3400 3401 For a logical multi-camera, bokeh may be implemented by stereo vision from sub-cameras 3402 with different field of view. As a result, when bokeh mode is enabled, the camera device 3403 may override android.scaler.cropRegion or android.control.zoomRatio, and the field of 3404 view may be smaller than when bokeh mode is off. 3405 </details> 3406 </entry> 3407 </controls> 3408 <dynamic> 3409 <clone entry="android.control.extendedSceneMode" kind="controls"> 3410 </clone> 3411 </dynamic> 3412 <static> 3413 <entry name="zoomRatioRange" type="float" visibility="public" 3414 type_notes="The range of zoom ratios that this camera device supports." 3415 container="array" typedef="rangeFloat" hwlevel="limited" hal_version="3.5" 3416 session_characteristics_key_since="35"> 3417 <array> 3418 <size>2</size> 3419 </array> 3420 <description> 3421 Minimum and maximum zoom ratios supported by this camera device. 3422 </description> 3423 <units>A pair of zoom ratio in floating-points: (minZoom, maxZoom)</units> 3424 <range> 3425 maxZoom >= 1.0 >= minZoom 3426 </range> 3427 <details> 3428 If the camera device supports zoom-out from 1x zoom, minZoom will be less than 1.0, and 3429 setting android.control.zoomRatio to values less than 1.0 increases the camera's field 3430 of view. 3431 </details> 3432 <hal_details> 3433 When the key is reported, the camera device's android.scaler.availableMaxDigitalZoom 3434 must be less than or equal to maxZoom. The camera framework makes sure to always 3435 control zoom via android.control.zoomRatio. The android.scaler.cropRegion tag is only 3436 used to do horizontal or vertical cropping (but not both) to achieve aspect ratio 3437 different than the camera sensor's native aspect ratio. 3438 3439 For a logical multi-camera device, this key must either be reported for both the logical 3440 camera device and all its physical sub-cameras, or none of them. 3441 3442 When the key is not reported, camera framework derives the application-facing 3443 zoomRatioRange to be (1, android.scaler.availableMaxDigitalZoom). 3444 </hal_details> 3445 </entry> 3446 </static> 3447 <controls> 3448 <entry name="zoomRatio" type="float" visibility="public" hwlevel="limited" 3449 hal_version="3.5"> 3450 <description> 3451 The desired zoom ratio 3452 </description> 3453 <range>android.control.zoomRatioRange</range> 3454 <details> 3455 Instead of using android.scaler.cropRegion for zoom, the application can now choose to 3456 use this tag to specify the desired zoom level. 3457 3458 By using this control, the application gains a simpler way to control zoom, which can 3459 be a combination of optical and digital zoom. For example, a multi-camera system may 3460 contain more than one lens with different focal lengths, and the user can use optical 3461 zoom by switching between lenses. Using zoomRatio has benefits in the scenarios below: 3462 3463 * Zooming in from a wide-angle lens to a telephoto lens: A floating-point ratio provides 3464 better precision compared to an integer value of android.scaler.cropRegion. 3465 * Zooming out from a wide lens to an ultrawide lens: zoomRatio supports zoom-out whereas 3466 android.scaler.cropRegion doesn't. 3467 3468 To illustrate, here are several scenarios of different zoom ratios, crop regions, 3469 and output streams, for a hypothetical camera device with an active array of size 3470 `(2000,1500)`. 3471 3472 * Camera Configuration: 3473 * Active array size: `2000x1500` (3 MP, 4:3 aspect ratio) 3474 * Output stream #1: `640x480` (VGA, 4:3 aspect ratio) 3475 * Output stream #2: `1280x720` (720p, 16:9 aspect ratio) 3476 * Case #1: 4:3 crop region with 2.0x zoom ratio 3477 * Zoomed field of view: 1/4 of original field of view 3478 * Crop region: `Rect(0, 0, 2000, 1500) // (left, top, right, bottom)` (post zoom) 3479 *  3480 * `640x480` stream source area: `(0, 0, 2000, 1500)` (equal to crop region) 3481 * `1280x720` stream source area: `(0, 187, 2000, 1312)` (letterboxed) 3482 * Case #2: 16:9 crop region with 2.0x zoom. 3483 * Zoomed field of view: 1/4 of original field of view 3484 * Crop region: `Rect(0, 187, 2000, 1312)` 3485 *  3486 * `640x480` stream source area: `(250, 187, 1750, 1312)` (pillarboxed) 3487 * `1280x720` stream source area: `(0, 187, 2000, 1312)` (equal to crop region) 3488 * Case #3: 1:1 crop region with 0.5x zoom out to ultrawide lens. 3489 * Zoomed field of view: 4x of original field of view (switched from wide lens to ultrawide lens) 3490 * Crop region: `Rect(250, 0, 1750, 1500)` 3491 *  3492 * `640x480` stream source area: `(250, 187, 1750, 1312)` (letterboxed) 3493 * `1280x720` stream source area: `(250, 328, 1750, 1172)` (letterboxed) 3494 3495 As seen from the graphs above, the coordinate system of cropRegion now changes to the 3496 effective after-zoom field-of-view, and is represented by the rectangle of (0, 0, 3497 activeArrayWith, activeArrayHeight). The same applies to AE/AWB/AF regions, and faces. 3498 This coordinate system change isn't applicable to RAW capture and its related 3499 metadata such as intrinsicCalibration and lensShadingMap. 3500 3501 Using the same hypothetical example above, and assuming output stream #1 (640x480) is 3502 the viewfinder stream, the application can achieve 2.0x zoom in one of two ways: 3503 3504 * zoomRatio = 2.0, scaler.cropRegion = (0, 0, 2000, 1500) 3505 * zoomRatio = 1.0 (default), scaler.cropRegion = (500, 375, 1500, 1125) 3506 3507 If the application intends to set aeRegions to be top-left quarter of the viewfinder 3508 field-of-view, the android.control.aeRegions should be set to (0, 0, 1000, 750) with 3509 zoomRatio set to 2.0. Alternatively, the application can set aeRegions to the equivalent 3510 region of (500, 375, 1000, 750) for zoomRatio of 1.0. If the application doesn't 3511 explicitly set android.control.zoomRatio, its value defaults to 1.0. 3512 3513 One limitation of controlling zoom using zoomRatio is that the android.scaler.cropRegion 3514 must only be used for letterboxing or pillarboxing of the sensor active array, and no 3515 FREEFORM cropping can be used with android.control.zoomRatio other than 1.0. If 3516 android.control.zoomRatio is not 1.0, and android.scaler.cropRegion is set to be 3517 windowboxing, the camera framework will override the android.scaler.cropRegion to be 3518 the active array. 3519 3520 In the capture request, if the application sets android.control.zoomRatio to a 3521 value != 1.0, the android.control.zoomRatio tag in the capture result reflects the 3522 effective zoom ratio achieved by the camera device, and the android.scaler.cropRegion 3523 adjusts for additional crops that are not zoom related. Otherwise, if the application 3524 sets android.control.zoomRatio to 1.0, or does not set it at all, the 3525 android.control.zoomRatio tag in the result metadata will also be 1.0. 3526 3527 When the application requests a physical stream for a logical multi-camera, the 3528 android.control.zoomRatio in the physical camera result metadata will be 1.0, and 3529 the android.scaler.cropRegion tag reflects the amount of zoom and crop done by the 3530 physical camera device. 3531 </details> 3532 <hal_details> 3533 For all capture request templates, this field must be set to 1.0 in order to have 3534 consistent field of views between different modes. 3535 </hal_details> 3536 </entry> 3537 </controls> 3538 <dynamic> 3539 <clone entry="android.control.zoomRatio" kind="controls"> 3540 </clone> 3541 </dynamic> 3542 <static> 3543 <entry name="availableHighSpeedVideoConfigurationsMaximumResolution" type="int32" 3544 visibility="hidden" container="array" typedef="highSpeedVideoConfiguration" 3545 hal_version="3.6"> 3546 <array> 3547 <size>5</size> 3548 <size>n</size> 3549 </array> 3550 <description> 3551 List of available high speed video size, fps range and max batch size configurations 3552 supported by the camera device, in the format of 3553 (width, height, fps_min, fps_max, batch_size_max), 3554 when android.sensor.pixelMode is set to 3555 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 3556 </description> 3557 <range> 3558 For each configuration, the fps_max &gt;= 120fps. 3559 </range> 3560 <details> 3561 Analogous to android.control.availableHighSpeedVideoConfigurations, for configurations 3562 which are applicable when android.sensor.pixelMode is set to 3563 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 3564 </details> 3565 <hal_details> 3566 Refer to hal details for android.control.availableHighSpeedVideoConfigurations. 3567 </hal_details> 3568 <tag id="V1" /> 3569 </entry> 3570 </static> 3571 <controls> 3572 <entry name="afRegionsSet" type="byte" visibility="fwk_only" 3573 enum="true" typedef="boolean"> 3574 <enum> 3575 <value>FALSE 3576 <notes>AF regions (android.control.afRegions) have not been set by the camera client. 3577 </notes> 3578 </value> 3579 <value>TRUE 3580 <notes> 3581 AF regions (android.control.afRegions) have been set by the camera client. 3582 </notes> 3583 </value> 3584 </enum> 3585 <description> 3586 Framework-only private key which informs camera fwk that the AF regions has been set 3587 by the client and those regions need not be corrected when android.sensor.pixelMode is 3588 set to MAXIMUM_RESOLUTION. 3589 </description> 3590 <details> 3591 This must be set to TRUE by the camera2 java fwk when the camera client sets 3592 android.control.afRegions. 3593 </details> 3594 </entry> 3595 <entry name="aeRegionsSet" type="byte" visibility="fwk_only" 3596 enum="true" typedef="boolean"> 3597 <enum> 3598 <value>FALSE 3599 <notes> AE regions (android.control.aeRegions) have not been set by the camera client. 3600 </notes> 3601 </value> 3602 <value>TRUE 3603 <notes> 3604 AE regions (android.control.aeRegions) have been set by the camera client. 3605 </notes> 3606 </value> 3607 </enum> 3608 <description> 3609 Framework-only private key which informs camera fwk that the AE regions has been set 3610 by the client and those regions need not be corrected when android.sensor.pixelMode is 3611 set to MAXIMUM_RESOLUTION. 3612 </description> 3613 <details> 3614 This must be set to TRUE by the camera2 java fwk when the camera client sets 3615 android.control.aeRegions. 3616 </details> 3617 </entry> 3618 <entry name="awbRegionsSet" type="byte" visibility="fwk_only" 3619 enum="true" typedef="boolean"> 3620 <enum> 3621 <value>FALSE 3622 <notes> AWB regions (android.control.awbRegions) have not been set by the camera client. 3623 </notes> 3624 </value> 3625 <value>TRUE 3626 <notes> 3627 AWB regions (android.control.awbRegions) have been set by the camera client. 3628 </notes> 3629 </value> 3630 </enum> 3631 <description> 3632 Framework-only private key which informs camera fwk that the AF regions has been set 3633 by the client and those regions need not be corrected when android.sensor.pixelMode is 3634 set to MAXIMUM_RESOLUTION. 3635 </description> 3636 <details> 3637 This must be set to TRUE by the camera2 java fwk when the camera client sets 3638 android.control.awbRegions. 3639 </details> 3640 </entry> 3641 <entry name="settingsOverride" type="int32" visibility="public" enum="true" 3642 hal_version="3.9"> 3643 <enum> 3644 <value>OFF 3645 <notes> 3646 No keys are applied sooner than the other keys when applying CaptureRequest 3647 settings to the camera device. This is the default value. 3648 </notes> 3649 </value> 3650 <value>ZOOM 3651 <notes> 3652 Zoom related keys are applied sooner than the other keys in the CaptureRequest. The 3653 zoom related keys are: 3654 3655 * android.control.zoomRatio 3656 * android.scaler.cropRegion 3657 * android.control.aeRegions 3658 * android.control.awbRegions 3659 * android.control.afRegions 3660 3661 Even though android.control.aeRegions, android.control.awbRegions, 3662 and android.control.afRegions are not directly zoom related, applications 3663 typically scale these regions together with android.scaler.cropRegion to have a 3664 consistent mapping within the current field of view. In this aspect, they are 3665 related to android.scaler.cropRegion and android.control.zoomRatio. 3666 </notes> 3667 </value> 3668 <value visibility="hidden" id="0x4000">VENDOR_START 3669 <notes> 3670 Vendor defined settingsOverride. These depend on vendor implementation. 3671 </notes> 3672 </value> 3673 </enum> 3674 <description>The desired CaptureRequest settings override with which certain keys are 3675 applied earlier so that they can take effect sooner. 3676 </description> 3677 <range>android.control.availableSettingsOverrides</range> 3678 <details> 3679 There are some CaptureRequest keys which can be applied earlier than others 3680 when controls within a CaptureRequest aren't required to take effect at the same time. 3681 One such example is zoom. Zoom can be applied at a later stage of the camera pipeline. 3682 As soon as the camera device receives the CaptureRequest, it can apply the requested 3683 zoom value onto an earlier request that's already in the pipeline, thus improves zoom 3684 latency. 3685 3686 This key's value in the capture result reflects whether the controls for this capture 3687 are overridden "by" a newer request. This means that if a capture request turns on 3688 settings override, the capture result of an earlier request will contain the key value 3689 of ZOOM. On the other hand, if a capture request has settings override turned on, 3690 but all newer requests have it turned off, the key's value in the capture result will 3691 be OFF because this capture isn't overridden by a newer capture. In the two examples 3692 below, the capture results columns illustrate the settingsOverride values in different 3693 scenarios. 3694 3695 Assuming the zoom settings override can speed up by 1 frame, below example illustrates 3696 the speed-up at the start of capture session: 3697 3698 Camera session created 3699 Request 1 (zoom=1.0x, override=ZOOM) -> 3700 Request 2 (zoom=1.2x, override=ZOOM) -> 3701 Request 3 (zoom=1.4x, override=ZOOM) -> Result 1 (zoom=1.2x, override=ZOOM) 3702 Request 4 (zoom=1.6x, override=ZOOM) -> Result 2 (zoom=1.4x, override=ZOOM) 3703 Request 5 (zoom=1.8x, override=ZOOM) -> Result 3 (zoom=1.6x, override=ZOOM) 3704 -> Result 4 (zoom=1.8x, override=ZOOM) 3705 -> Result 5 (zoom=1.8x, override=OFF) 3706 3707 The application can turn on settings override and use zoom as normal. The example 3708 shows that the later zoom values (1.2x, 1.4x, 1.6x, and 1.8x) overwrite the zoom 3709 values (1.0x, 1.2x, 1.4x, and 1.8x) of earlier requests (#1, #2, #3, and #4). 3710 3711 The application must make sure the settings override doesn't interfere with user 3712 journeys requiring simultaneous application of all controls in CaptureRequest on the 3713 requested output targets. For example, if the application takes a still capture using 3714 CameraCaptureSession#capture, and the repeating request immediately sets a different 3715 zoom value using override, the inflight still capture could have its zoom value 3716 overwritten unexpectedly. 3717 3718 So the application is strongly recommended to turn off settingsOverride when taking 3719 still/burst captures, and turn it back on when there is only repeating viewfinder 3720 request and no inflight still/burst captures. 3721 3722 Below is the example demonstrating the transitions in and out of the 3723 settings override: 3724 3725 Request 1 (zoom=1.0x, override=OFF) 3726 Request 2 (zoom=1.2x, override=OFF) 3727 Request 3 (zoom=1.4x, override=ZOOM) -> Result 1 (zoom=1.0x, override=OFF) 3728 Request 4 (zoom=1.6x, override=ZOOM) -> Result 2 (zoom=1.4x, override=ZOOM) 3729 Request 5 (zoom=1.8x, override=OFF) -> Result 3 (zoom=1.6x, override=ZOOM) 3730 -> Result 4 (zoom=1.6x, override=OFF) 3731 -> Result 5 (zoom=1.8x, override=OFF) 3732 3733 This example shows that: 3734 3735 * The application "ramps in" settings override by setting the control to ZOOM. 3736 In the example, request #3 enables zoom settings override. Because the camera device 3737 can speed up applying zoom by 1 frame, the outputs of request #2 has 1.4x zoom, the 3738 value specified in request #3. 3739 * The application "ramps out" of settings override by setting the control to OFF. In 3740 the example, request #5 changes the override to OFF. Because request #4's zoom 3741 takes effect in result #3, result #4's zoom remains the same until new value takes 3742 effect in result #5. 3743 </details> 3744 <hal_details> 3745 The HAL must set this value to OFF in all of the Capture templates. 3746 3747 Typically the HAL unblocks processCaptureRequest at the same rate as the sensor capture, 3748 and the HAL queues the capture settings in its pipeline when processCaptureRequest 3749 returns. However, when the settings override is enabled, the HAL can optimize the 3750 overridden controls' latency by applying them as soon as processCaptureRequest is 3751 called, rather than when it's unblocked. 3752 3753 For devices launching with API level 35 or newer, to avoid regression on zoom 3754 smoothness, when zoom settings override is on during pinch zoom (zoom value gradually 3755 changes), the zoom effect in the camera output must not become more jittery. More 3756 specifically, the variation of zoom pipeline latency must not increase. The latency 3757 improvement must be at least 1 frame regardless of zoom in or zoom out. 3758 3759 For devices launched before API level 35, if zoom settings override is on, when 3760 zooming in, the HAL must be able to apply the zoom related settings at least 1 3761 frame ahead. 3762 </hal_details> 3763 </entry> 3764 </controls> 3765 <static> 3766 <entry name="availableSettingsOverrides" type="int32" visibility="public" 3767 optional="true" type_notes="list of enums" container="array" typedef="enumList" 3768 hal_version="3.9"> 3769 <array> 3770 <size>n</size> 3771 </array> 3772 <description>List of available settings overrides supported by the camera device that can 3773 be used to speed up certain controls. 3774 </description> 3775 <range>Any value listed in android.control.settingsOverride</range> 3776 <details>When not all controls within a CaptureRequest are required to take effect 3777 at the same time on the outputs, the camera device may apply certain request keys sooner 3778 to improve latency. This list contains such supported settings overrides. Each settings 3779 override corresponds to a set of CaptureRequest keys that can be sped up when applying. 3780 3781 A supported settings override can be passed in via 3782 {@link android.hardware.camera2.CaptureRequest#CONTROL_SETTINGS_OVERRIDE}, and the 3783 CaptureRequest keys corresponding to the override are applied as soon as possible, not 3784 bound by per-frame synchronization. See android.control.settingsOverride for the 3785 CaptureRequest keys for each override. 3786 3787 OFF is always included in this list. 3788 </details> 3789 </entry> 3790 </static> 3791 <dynamic> 3792 <clone entry="android.control.settingsOverride" kind="controls"> 3793 </clone> 3794 <entry name="settingsOverridingFrameNumber" type="int32" visibility="system" 3795 hal_version="3.9"> 3796 <description>The frame number of the newer request overriding this capture. 3797 </description> 3798 <details>Must be equal to the frame number of the result if this capture isn't 3799 overridden by a newer request, i.e. if android.control.settingsOverride is OFF 3800 in the capture result. On the other hand, if the capture is overridden by a newer 3801 request, the value of this tag (unsigned) must be larger than the frame number of 3802 the capture result.</details> 3803 </entry> 3804 </dynamic> 3805 <controls> 3806 <entry name="autoframing" type="byte" visibility="public" 3807 enum="true" hwlevel="limited" hal_version="3.9"> 3808 <enum> 3809 <value>OFF 3810 <notes> 3811 Disable autoframing. 3812 </notes> 3813 </value> 3814 <value>ON 3815 <notes> 3816 Enable autoframing to keep people in the frame's field of view. 3817 </notes> 3818 </value> 3819 <value visibility="hidden">AUTO 3820 <notes> 3821 Automatically select ON or OFF based on the system level preferences. 3822 </notes> 3823 </value> 3824 </enum> 3825 <description> 3826 Automatic crop, pan and zoom to keep objects in the center of the frame. 3827 </description> 3828 <details> 3829 Auto-framing is a special mode provided by the camera device to dynamically crop, zoom 3830 or pan the camera feed to try to ensure that the people in a scene occupy a reasonable 3831 portion of the viewport. It is primarily designed to support video calling in 3832 situations where the user isn't directly in front of the device, especially for 3833 wide-angle cameras. 3834 android.scaler.cropRegion and android.control.zoomRatio in CaptureResult will be used 3835 to denote the coordinates of the auto-framed region. 3836 Zoom and video stabilization controls are disabled when auto-framing is enabled. The 3A 3837 regions must map the screen coordinates into the scaler crop returned from the capture 3838 result instead of using the active array sensor. 3839 </details> 3840 <hal_details> 3841 While auto-framing is ON, the aspect ratio of the auto-framed region must match the 3842 aspect ratio of the configured output stream. 3843 When reporting CaptureResult, SCALER_CROP_REGION might not adequately describe the 3844 actual sensor pixels. In this case, it is acceptable for the returned parameters to only 3845 be an approximation of the image sensor region that is actually used. 3846 When auto-framing is turned off, the transition should be immediate, with no panning or 3847 zooming to transition to the settings requested by the app. When it is turned on, the 3848 transition can be immediate or smooth. 3849 </hal_details> 3850 </entry> 3851 </controls> 3852 <static> 3853 <entry name="autoframingAvailable" type="byte" visibility="public" enum="true" 3854 typedef="boolean" hwlevel="limited" hal_version="3.9"> 3855 <enum> 3856 <value>FALSE</value> 3857 <value>TRUE</value> 3858 </enum> 3859 <description>Whether the camera device supports android.control.autoframing. 3860 </description> 3861 <details> 3862 Will be `false` if auto-framing is not available. 3863 </details> 3864 </entry> 3865 </static> 3866 <dynamic> 3867 <clone entry="android.control.autoframing" kind="controls"> 3868 </clone> 3869 <entry name="autoframingState" type="byte" visibility="public" 3870 enum="true" hwlevel="limited" hal_version="3.9"> 3871 <enum> 3872 <value>INACTIVE 3873 <notes> 3874 Auto-framing is inactive. 3875 </notes> 3876 </value> 3877 <value>FRAMING 3878 <notes> 3879 Auto-framing is in process - either zooming in, zooming out or pan is taking place. 3880 </notes> 3881 </value> 3882 <value>CONVERGED 3883 <notes> 3884 Auto-framing has reached a stable state (frame/fov is not being adjusted). The state 3885 may transition back to FRAMING if the scene changes. 3886 </notes> 3887 </value> 3888 </enum> 3889 <description>Current state of auto-framing. 3890 </description> 3891 <details> 3892 When the camera doesn't have auto-framing available (i.e 3893 `android.control.autoframingAvailable` == false) or it is not enabled (i.e 3894 `android.control.autoframing` == OFF), the state will always be INACTIVE. 3895 Other states indicate the current auto-framing state: 3896 3897 * When `android.control.autoframing` is set to ON, auto-framing will take 3898 place. While the frame is aligning itself to center the object (doing things like 3899 zooming in, zooming out or pan), the state will be FRAMING. 3900 * When field of view is not being adjusted anymore and has reached a stable state, the 3901 state will be CONVERGED. 3902 </details> 3903 </entry> 3904 </dynamic> 3905 <static> 3906 <entry name="lowLightBoostInfoLuminanceRange" type="float" visibility="public" 3907 optional="true" container="array" typedef="rangeFloat" 3908 aconfig_flag="camera_ae_mode_low_light_boost" hal_version="3.10"> 3909 <array> 3910 <size>2</size> 3911 </array> 3912 <description> 3913 The operating luminance range of low light boost measured in lux (lx). 3914 </description> 3915 <range> 3916 The lower bound indicates the lowest scene luminance value the AE mode 3917 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY' can operate within. Scenes of lower luminance 3918 than this may receive less brightening, increased noise, or artifacts. 3919 3920 The upper bound indicates the luminance threshold at the point when the mode is enabled. 3921 For example, 'Range[0.3, 30.0]' defines 0.3 lux being the lowest scene luminance the 3922 mode can reliably support. 30.0 lux represents the threshold when this mode is 3923 activated. Scenes measured at less than or equal to 30 lux will activate low light 3924 boost. 3925 3926 If this key is defined, then the AE mode 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY' will 3927 also be present. 3928 </range> 3929 </entry> 3930 </static> 3931 <dynamic> 3932 <entry name="lowLightBoostState" type="byte" visibility="public" optional="true" enum="true" 3933 aconfig_flag="camera_ae_mode_low_light_boost" hal_version="3.10"> 3934 <enum> 3935 <value>INACTIVE 3936 <notes> 3937 The AE mode 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY' is enabled but not applied. 3938 </notes></value> 3939 <value>ACTIVE 3940 <notes> 3941 The AE mode 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY' is enabled and applied. 3942 </notes></value> 3943 </enum> 3944 <description> 3945 Current state of the low light boost AE mode. 3946 </description> 3947 <details> 3948 When low light boost is enabled by setting the AE mode to 3949 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY', it can dynamically apply a low light 3950 boost when the light level threshold is exceeded. 3951 3952 This state indicates when low light boost is 'ACTIVE' and applied. Similarly, it can 3953 indicate when it is not being applied by returning 'INACTIVE'. 3954 3955 This key will be absent from the CaptureResult if AE mode is not set to 3956 'ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY. 3957 3958 The default value will always be 'INACTIVE'. 3959 </details> 3960 </entry> 3961 </dynamic> 3962 </section> 3963 <section name="demosaic"> 3964 <controls> 3965 <entry name="mode" type="byte" enum="true"> 3966 <enum> 3967 <value>FAST 3968 <notes>Minimal or no slowdown of frame rate compared to 3969 Bayer RAW output.</notes></value> 3970 <value>HIGH_QUALITY 3971 <notes>Improved processing quality but the frame rate might be slowed down 3972 relative to raw output.</notes></value> 3973 </enum> 3974 <description>Controls the quality of the demosaicing 3975 processing.</description> 3976 <tag id="FUTURE" /> 3977 </entry> 3978 </controls> 3979 </section> 3980 <section name="edge"> 3981 <controls> 3982 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 3983 <enum> 3984 <value>OFF 3985 <notes>No edge enhancement is applied.</notes></value> 3986 <value>FAST 3987 <notes>Apply edge enhancement at a quality level that does not slow down frame rate 3988 relative to sensor output. It may be the same as OFF if edge enhancement will 3989 slow down frame rate relative to sensor.</notes></value> 3990 <value>HIGH_QUALITY 3991 <notes>Apply high-quality edge enhancement, at a cost of possibly reduced output frame rate. 3992 </notes></value> 3993 <value optional="true">ZERO_SHUTTER_LAG <notes>Edge enhancement is applied at different 3994 levels for different output streams, based on resolution. Streams at maximum recording 3995 resolution (see {@link 3996 android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession}) 3997 or below have edge enhancement applied, while higher-resolution streams have no edge 3998 enhancement applied. The level of edge enhancement for low-resolution streams is tuned 3999 so that frame rate is not impacted, and the quality is equal to or better than FAST 4000 (since it is only applied to lower-resolution outputs, quality may improve from FAST). 4001 4002 This mode is intended to be used by applications operating in a zero-shutter-lag mode 4003 with YUV or PRIVATE reprocessing, where the application continuously captures 4004 high-resolution intermediate buffers into a circular buffer, from which a final image is 4005 produced via reprocessing when a user takes a picture. For such a use case, the 4006 high-resolution buffers must not have edge enhancement applied to maximize efficiency of 4007 preview and to avoid double-applying enhancement when reprocessed, while low-resolution 4008 buffers (used for recording or preview, generally) need edge enhancement applied for 4009 reasonable preview quality. 4010 4011 This mode is guaranteed to be supported by devices that support either the 4012 YUV_REPROCESSING or PRIVATE_REPROCESSING capabilities 4013 (android.request.availableCapabilities lists either of those capabilities) and it will 4014 be the default mode for CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template. 4015 </notes></value> 4016 </enum> 4017 <description>Operation mode for edge 4018 enhancement.</description> 4019 <range>android.edge.availableEdgeModes</range> 4020 <details>Edge enhancement improves sharpness and details in the captured image. OFF means 4021 no enhancement will be applied by the camera device. 4022 4023 FAST/HIGH_QUALITY both mean camera device determined enhancement 4024 will be applied. HIGH_QUALITY mode indicates that the 4025 camera device will use the highest-quality enhancement algorithms, 4026 even if it slows down capture rate. FAST means the camera device will 4027 not slow down capture rate when applying edge enhancement. FAST may be the same as OFF if 4028 edge enhancement will slow down capture rate. Every output stream will have a similar 4029 amount of enhancement applied. 4030 4031 ZERO_SHUTTER_LAG is meant to be used by applications that maintain a continuous circular 4032 buffer of high-resolution images during preview and reprocess image(s) from that buffer 4033 into a final capture when triggered by the user. In this mode, the camera device applies 4034 edge enhancement to low-resolution streams (below maximum recording resolution) to 4035 maximize preview quality, but does not apply edge enhancement to high-resolution streams, 4036 since those will be reprocessed later if necessary. 4037 4038 For YUV_REPROCESSING, these FAST/HIGH_QUALITY modes both mean that the camera 4039 device will apply FAST/HIGH_QUALITY YUV-domain edge enhancement, respectively. 4040 The camera device may adjust its internal edge enhancement parameters for best 4041 image quality based on the android.reprocess.effectiveExposureFactor, if it is set. 4042 </details> 4043 <hal_details> 4044 For YUV_REPROCESSING The HAL can use android.reprocess.effectiveExposureFactor to 4045 adjust the internal edge enhancement reduction parameters appropriately to get the best 4046 quality images. 4047 </hal_details> 4048 <tag id="V1" /> 4049 <tag id="REPROC" /> 4050 </entry> 4051 <entry name="strength" type="byte"> 4052 <description>Control the amount of edge enhancement 4053 applied to the images</description> 4054 <units>1-10; 10 is maximum sharpening</units> 4055 <tag id="FUTURE" /> 4056 </entry> 4057 </controls> 4058 <static> 4059 <entry name="availableEdgeModes" type="byte" visibility="public" 4060 type_notes="list of enums" container="array" typedef="enumList" 4061 hwlevel="full"> 4062 <array> 4063 <size>n</size> 4064 </array> 4065 <description> 4066 List of edge enhancement modes for android.edge.mode that are supported by this camera 4067 device. 4068 </description> 4069 <range>Any value listed in android.edge.mode</range> 4070 <details> 4071 Full-capability camera devices must always support OFF; camera devices that support 4072 YUV_REPROCESSING or PRIVATE_REPROCESSING will list ZERO_SHUTTER_LAG; all devices will 4073 list FAST. 4074 </details> 4075 <hal_details> 4076 HAL must support both FAST and HIGH_QUALITY if edge enhancement control is available 4077 on the camera device, but the underlying implementation can be the same for both modes. 4078 That is, if the highest quality implementation on the camera device does not slow down 4079 capture rate, then FAST and HIGH_QUALITY will generate the same output. 4080 </hal_details> 4081 <tag id="V1" /> 4082 <tag id="REPROC" /> 4083 </entry> 4084 </static> 4085 <dynamic> 4086 <clone entry="android.edge.mode" kind="controls"> 4087 <tag id="V1" /> 4088 <tag id="REPROC" /> 4089 </clone> 4090 </dynamic> 4091 </section> 4092 <section name="flash"> 4093 <controls> 4094 <entry name="firingPower" type="byte"> 4095 <description>Power for flash firing/torch</description> 4096 <units>10 is max power; 0 is no flash. Linear</units> 4097 <range>0 - 10</range> 4098 <details>Power for snapshot may use a different scale than 4099 for torch mode. Only one entry for torch mode will be 4100 used</details> 4101 <tag id="FUTURE" /> 4102 </entry> 4103 <entry name="firingTime" type="int64"> 4104 <description>Firing time of flash relative to start of 4105 exposure</description> 4106 <units>nanoseconds</units> 4107 <range>0-(exposure time-flash duration)</range> 4108 <details>Clamped to (0, exposure time - flash 4109 duration).</details> 4110 <tag id="FUTURE" /> 4111 </entry> 4112 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 4113 <enum> 4114 <value>OFF 4115 <notes> 4116 Do not fire the flash for this capture. 4117 </notes> 4118 </value> 4119 <value>SINGLE 4120 <notes> 4121 If the flash is available and charged, fire flash 4122 for this capture. 4123 </notes> 4124 </value> 4125 <value>TORCH 4126 <notes> 4127 Transition flash to continuously on. 4128 </notes> 4129 </value> 4130 </enum> 4131 <description>The desired mode for for the camera device's flash control.</description> 4132 <details> 4133 This control is only effective when flash unit is available 4134 (`android.flash.info.available == true`). 4135 4136 When this control is used, the android.control.aeMode must be set to ON or OFF. 4137 Otherwise, the camera device auto-exposure related flash control (ON_AUTO_FLASH, 4138 ON_ALWAYS_FLASH, or ON_AUTO_FLASH_REDEYE) will override this control. 4139 4140 When set to OFF, the camera device will not fire flash for this capture. 4141 4142 When set to SINGLE, the camera device will fire flash regardless of the camera 4143 device's auto-exposure routine's result. When used in still capture case, this 4144 control should be used along with auto-exposure (AE) precapture metering sequence 4145 (android.control.aePrecaptureTrigger), otherwise, the image may be incorrectly exposed. 4146 4147 When set to TORCH, the flash will be on continuously. This mode can be used 4148 for use cases such as preview, auto-focus assist, still capture, or video recording. 4149 4150 The flash status will be reported by android.flash.state in the capture result metadata. 4151 </details> 4152 <tag id="BC" /> 4153 </entry> 4154 </controls> 4155 <static> 4156 <namespace name="info"> 4157 <entry name="available" type="byte" visibility="public" enum="true" 4158 typedef="boolean" hwlevel="legacy"> 4159 <enum> 4160 <value>FALSE</value> 4161 <value>TRUE</value> 4162 </enum> 4163 <description>Whether this camera device has a 4164 flash unit.</description> 4165 <details> 4166 Will be `false` if no flash is available. 4167 4168 If there is no flash unit, none of the flash controls do 4169 anything.</details> 4170 <tag id="BC" /> 4171 </entry> 4172 <entry name="chargeDuration" type="int64"> 4173 <description>Time taken before flash can fire 4174 again</description> 4175 <units>nanoseconds</units> 4176 <range>0-1e9</range> 4177 <details>1 second too long/too short for recharge? Should 4178 this be power-dependent?</details> 4179 <tag id="FUTURE" /> 4180 </entry> 4181 <entry name="strengthMaximumLevel" type="int32" visibility="public" hal_version="3.8"> 4182 <description>Maximum flashlight brightness level. 4183 </description> 4184 <details>If this value is greater than 1, then the device supports controlling the 4185 flashlight brightness level via 4186 {@link android.hardware.camera2.CameraManager#turnOnTorchWithStrengthLevel}. 4187 If this value is equal to 1, flashlight brightness control is not supported. 4188 The value for this key will be null for devices with no flash unit. 4189 4190 The maximum value is guaranteed to be safe to use for an indefinite duration in 4191 terms of device flashlight lifespan, but may be too bright for comfort for many 4192 use cases. Use the default torch brightness value to avoid problems with an 4193 over-bright flashlight. 4194 </details> 4195 </entry> 4196 <entry name="strengthDefaultLevel" type="int32" visibility="public" hal_version="3.8"> 4197 <description>Default flashlight brightness level to be set via 4198 {@link android.hardware.camera2.CameraManager#turnOnTorchWithStrengthLevel}. 4199 </description> 4200 <details> 4201 If flash unit is available this will be greater than or equal to 1 and less 4202 or equal to `android.flash.info.strengthMaximumLevel`. 4203 4204 Setting flashlight brightness above the default level 4205 (i.e.`android.flash.info.strengthDefaultLevel`) may make the device more 4206 likely to reach thermal throttling conditions and slow down, or drain the 4207 battery quicker than normal. To minimize such issues, it is recommended to 4208 start the flashlight at this default brightness until a user explicitly requests 4209 a brighter level. 4210 Note that the value for this key will be null for devices with no flash unit. 4211 The default level should always be > 0. 4212 </details> 4213 </entry> 4214 </namespace> 4215 <entry name="colorTemperature" type="byte"> 4216 <description>The x,y whitepoint of the 4217 flash</description> 4218 <units>pair of floats</units> 4219 <range>0-1 for both</range> 4220 <tag id="FUTURE" /> 4221 </entry> 4222 <entry name="maxEnergy" type="byte"> 4223 <description>Max energy output of the flash for a full 4224 power single flash</description> 4225 <units>lumen-seconds</units> 4226 <range>&gt;= 0</range> 4227 <tag id="FUTURE" /> 4228 </entry> 4229 </static> 4230 <dynamic> 4231 <clone entry="android.flash.firingPower" kind="controls"> 4232 </clone> 4233 <clone entry="android.flash.firingTime" kind="controls"> 4234 </clone> 4235 <clone entry="android.flash.mode" kind="controls"></clone> 4236 <entry name="state" type="byte" visibility="public" enum="true" 4237 hwlevel="limited"> 4238 <enum> 4239 <value>UNAVAILABLE 4240 <notes>No flash on camera.</notes></value> 4241 <value>CHARGING 4242 <notes>Flash is charging and cannot be fired.</notes></value> 4243 <value>READY 4244 <notes>Flash is ready to fire.</notes></value> 4245 <value>FIRED 4246 <notes>Flash fired for this capture.</notes></value> 4247 <value>PARTIAL 4248 <notes>Flash partially illuminated this frame. 4249 4250 This is usually due to the next or previous frame having 4251 the flash fire, and the flash spilling into this capture 4252 due to hardware limitations.</notes></value> 4253 </enum> 4254 <description>Current state of the flash 4255 unit.</description> 4256 <details> 4257 When the camera device doesn't have flash unit 4258 (i.e. `android.flash.info.available == false`), this state will always be UNAVAILABLE. 4259 Other states indicate the current flash status. 4260 4261 In certain conditions, this will be available on LEGACY devices: 4262 4263 * Flash-less cameras always return UNAVAILABLE. 4264 * Using android.control.aeMode `==` ON_ALWAYS_FLASH 4265 will always return FIRED. 4266 * Using android.flash.mode `==` TORCH 4267 will always return FIRED. 4268 4269 In all other conditions the state will not be available on 4270 LEGACY devices (i.e. it will be `null`). 4271 </details> 4272 </entry> 4273 </dynamic> 4274 <controls> 4275 <entry name="strengthLevel" type="int32" visibility="public" hwlevel="legacy" 4276 aconfig_flag="camera_manual_flash_strength_control" hal_version="3.10"> 4277 <description>Flash strength level to be used when manual flash control is active. 4278 </description> 4279 <range>`[1-android.flash.torchStrengthMaxLevel]` when the android.flash.mode is 4280 set to TORCH; 4281 `[1-android.flash.singleStrengthMaxLevel]` when the android.flash.mode is 4282 set to SINGLE 4283 </range> 4284 <details>Flash strength level to use in capture mode i.e. when the applications control 4285 flash with either `SINGLE` or `TORCH` mode. 4286 4287 Use android.flash.singleStrengthMaxLevel and 4288 android.flash.torchStrengthMaxLevel to check whether the device supports 4289 flash strength control or not. 4290 If the values of android.flash.singleStrengthMaxLevel and 4291 android.flash.torchStrengthMaxLevel are greater than 1, 4292 then the device supports manual flash strength control. 4293 4294 If the android.flash.mode `==` `TORCH` the value must be &gt;= 1 4295 and &lt;= android.flash.torchStrengthMaxLevel. 4296 If the application doesn't set the key and 4297 android.flash.torchStrengthMaxLevel &gt; 1, 4298 then the flash will be fired at the default level set by HAL in 4299 android.flash.torchStrengthDefaultLevel. 4300 If the android.flash.mode `==` `SINGLE`, then the value must be &gt;= 1 4301 and &lt;= android.flash.singleStrengthMaxLevel. 4302 If the application does not set this key and 4303 android.flash.singleStrengthMaxLevel &gt; 1, 4304 then the flash will be fired at the default level set by HAL 4305 in android.flash.singleStrengthDefaultLevel. 4306 If android.control.aeMode is set to any of `ON_AUTO_FLASH`, `ON_ALWAYS_FLASH`, 4307 `ON_AUTO_FLASH_REDEYE`, `ON_EXTERNAL_FLASH` values, then the strengthLevel will be ignored. 4308 </details> 4309 </entry> 4310 </controls> 4311 <static> 4312 <entry name="singleStrengthMaxLevel" type="int32" visibility="public" hwlevel="legacy" 4313 aconfig_flag="camera_manual_flash_strength_control" hal_version="3.10"> 4314 <description>Maximum flash brightness level for manual flash control in `SINGLE` mode. 4315 </description> 4316 <details> 4317 Maximum flash brightness level in camera capture mode and 4318 android.flash.mode set to `SINGLE`. 4319 Value will be &gt; 1 if the manual flash strength control feature is supported, 4320 otherwise the value will be equal to 1. 4321 Note that this level is just a number of supported levels (the granularity of control). 4322 There is no actual physical power units tied to this level. 4323 </details> 4324 </entry> 4325 <entry name="singleStrengthDefaultLevel" type="int32" visibility="public" hwlevel="legacy" 4326 aconfig_flag="camera_manual_flash_strength_control" hal_version="3.10"> 4327 <description>Default flash brightness level for manual flash control in `SINGLE` mode. 4328 </description> 4329 <details> 4330 If flash unit is available this will be greater than or equal to 1 and less 4331 or equal to android.flash.singleStrengthMaxLevel. 4332 Note for devices that do not support the manual flash strength control 4333 feature, this level will always be equal to 1. 4334 </details> 4335 </entry> 4336 <entry name="torchStrengthMaxLevel" type="int32" visibility="public" hwlevel="legacy" 4337 aconfig_flag="camera_manual_flash_strength_control" hal_version="3.10"> 4338 <description>Maximum flash brightness level for manual flash control in `TORCH` mode 4339 </description> 4340 <details> 4341 Maximum flash brightness level in camera capture mode and 4342 android.flash.mode set to `TORCH`. 4343 Value will be &gt; 1 if the manual flash strength control feature is supported, 4344 otherwise the value will be equal to 1. 4345 4346 Note that this level is just a number of supported levels(the granularity of control). 4347 There is no actual physical power units tied to this level. 4348 There is no relation between android.flash.torchStrengthMaxLevel and 4349 android.flash.singleStrengthMaxLevel i.e. the ratio of 4350 android.flash.torchStrengthMaxLevel:android.flash.singleStrengthMaxLevel 4351 is not guaranteed to be the ratio of actual brightness. 4352 </details> 4353 </entry> 4354 <entry name="torchStrengthDefaultLevel" type="int32" visibility="public" hwlevel="legacy" 4355 aconfig_flag="camera_manual_flash_strength_control" hal_version="3.10"> 4356 <description>Default flash brightness level for manual flash control in `TORCH` mode 4357 </description> 4358 <details> 4359 If flash unit is available this will be greater than or equal to 1 and less 4360 or equal to android.flash.torchStrengthMaxLevel. 4361 Note for the devices that do not support the manual flash strength control feature, 4362 this level will always be equal to 1. 4363 </details> 4364 </entry> 4365 </static> 4366 <dynamic> 4367 <clone entry="android.flash.strengthLevel" kind="controls"> 4368 </clone> 4369 </dynamic> 4370 </section> 4371 <section name="hotPixel"> 4372 <controls> 4373 <entry name="mode" type="byte" visibility="public" enum="true"> 4374 <enum> 4375 <value>OFF 4376 <notes> 4377 No hot pixel correction is applied. 4378 4379 The frame rate must not be reduced relative to sensor raw output 4380 for this option. 4381 4382 The hotpixel map may be returned in android.statistics.hotPixelMap. 4383 </notes> 4384 </value> 4385 <value>FAST 4386 <notes> 4387 Hot pixel correction is applied, without reducing frame 4388 rate relative to sensor raw output. 4389 4390 The hotpixel map may be returned in android.statistics.hotPixelMap. 4391 </notes> 4392 </value> 4393 <value>HIGH_QUALITY 4394 <notes> 4395 High-quality hot pixel correction is applied, at a cost 4396 of possibly reduced frame rate relative to sensor raw output. 4397 4398 The hotpixel map may be returned in android.statistics.hotPixelMap. 4399 </notes> 4400 </value> 4401 </enum> 4402 <description> 4403 Operational mode for hot pixel correction. 4404 </description> 4405 <range>android.hotPixel.availableHotPixelModes</range> 4406 <details> 4407 Hotpixel correction interpolates out, or otherwise removes, pixels 4408 that do not accurately measure the incoming light (i.e. pixels that 4409 are stuck at an arbitrary value or are oversensitive). 4410 </details> 4411 <tag id="V1" /> 4412 <tag id="RAW" /> 4413 </entry> 4414 </controls> 4415 <static> 4416 <entry name="availableHotPixelModes" type="byte" visibility="public" 4417 type_notes="list of enums" container="array" typedef="enumList"> 4418 <array> 4419 <size>n</size> 4420 </array> 4421 <description> 4422 List of hot pixel correction modes for android.hotPixel.mode that are supported by this 4423 camera device. 4424 </description> 4425 <range>Any value listed in android.hotPixel.mode</range> 4426 <details> 4427 FULL mode camera devices will always support FAST. 4428 </details> 4429 <hal_details> 4430 To avoid performance issues, there will be significantly fewer hot 4431 pixels than actual pixels on the camera sensor. 4432 HAL must support both FAST and HIGH_QUALITY if hot pixel correction control is available 4433 on the camera device, but the underlying implementation can be the same for both modes. 4434 That is, if the highest quality implementation on the camera device does not slow down 4435 capture rate, then FAST and HIGH_QUALITY will generate the same output. 4436 </hal_details> 4437 <tag id="V1" /> 4438 <tag id="RAW" /> 4439 </entry> 4440 </static> 4441 <dynamic> 4442 <clone entry="android.hotPixel.mode" kind="controls"> 4443 <tag id="V1" /> 4444 <tag id="RAW" /> 4445 </clone> 4446 </dynamic> 4447 </section> 4448 <section name="jpeg"> 4449 <controls> 4450 <entry name="gpsLocation" type="byte" visibility="java_public" synthetic="true" 4451 typedef="location" hwlevel="legacy"> 4452 <description> 4453 A location object to use when generating image GPS metadata. 4454 </description> 4455 <details> 4456 Setting a location object in a request will include the GPS coordinates of the location 4457 into any JPEG images captured based on the request. These coordinates can then be 4458 viewed by anyone who receives the JPEG image. 4459 4460 This tag is also used for HEIC image capture. 4461 </details> 4462 </entry> 4463 <entry name="gpsCoordinates" type="double" visibility="ndk_public" 4464 type_notes="latitude, longitude, altitude. First two in degrees, the third in meters" 4465 container="array" hwlevel="legacy"> 4466 <array> 4467 <size>3</size> 4468 </array> 4469 <description>GPS coordinates to include in output JPEG 4470 EXIF.</description> 4471 <range>(-180 - 180], [-90,90], [-inf, inf]</range> 4472 <details>This tag is also used for HEIC image capture.</details> 4473 <tag id="BC" /> 4474 </entry> 4475 <entry name="gpsProcessingMethod" type="byte" visibility="ndk_public" 4476 typedef="string" hwlevel="legacy"> 4477 <description>32 characters describing GPS algorithm to 4478 include in EXIF.</description> 4479 <units>UTF-8 null-terminated string</units> 4480 <details>This tag is also used for HEIC image capture.</details> 4481 <tag id="BC" /> 4482 </entry> 4483 <entry name="gpsTimestamp" type="int64" visibility="ndk_public" hwlevel="legacy"> 4484 <description>Time GPS fix was made to include in 4485 EXIF.</description> 4486 <units>UTC in seconds since January 1, 1970</units> 4487 <details>This tag is also used for HEIC image capture.</details> 4488 <tag id="BC" /> 4489 </entry> 4490 <entry name="orientation" type="int32" visibility="public" hwlevel="legacy"> 4491 <description>The orientation for a JPEG image.</description> 4492 <units>Degrees in multiples of 90</units> 4493 <range>0, 90, 180, 270</range> 4494 <details> 4495 The clockwise rotation angle in degrees, relative to the orientation 4496 to the camera, that the JPEG picture needs to be rotated by, to be viewed 4497 upright. 4498 4499 Camera devices may either encode this value into the JPEG EXIF header, or 4500 rotate the image data to match this orientation. When the image data is rotated, 4501 the thumbnail data will also be rotated. Additionally, in the case where the image data 4502 is rotated, {@link android.media.Image#getWidth} and {@link android.media.Image#getHeight} 4503 will not be updated to reflect the height and width of the rotated image. 4504 4505 Note that this orientation is relative to the orientation of the camera sensor, given 4506 by android.sensor.orientation. 4507 4508 To translate from the device orientation given by the Android sensor APIs for camera 4509 sensors which are not EXTERNAL, the following sample code may be used: 4510 4511 private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) { 4512 if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0; 4513 int sensorOrientation = c.get(CameraCharacteristics.SENSOR_ORIENTATION); 4514 4515 // Round device orientation to a multiple of 90 4516 deviceOrientation = (deviceOrientation + 45) / 90 * 90; 4517 4518 // Reverse device orientation for front-facing cameras 4519 boolean facingFront = c.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_FRONT; 4520 if (facingFront) deviceOrientation = -deviceOrientation; 4521 4522 // Calculate desired JPEG orientation relative to camera orientation to make 4523 // the image upright relative to the device orientation 4524 int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360; 4525 4526 return jpegOrientation; 4527 } 4528 4529 For EXTERNAL cameras the sensor orientation will always be set to 0 and the facing will 4530 also be set to EXTERNAL. The above code is not relevant in such case. 4531 4532 This tag is also used to describe the orientation of the HEIC image capture, in which 4533 case the rotation is reflected by 4534 {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}, and not by 4535 rotating the image data itself. 4536 </details> 4537 <tag id="BC" /> 4538 </entry> 4539 <entry name="quality" type="byte" visibility="public" hwlevel="legacy"> 4540 <description>Compression quality of the final JPEG 4541 image.</description> 4542 <range>1-100; larger is higher quality</range> 4543 <details>85-95 is typical usage range. This tag is also used to describe the quality 4544 of the HEIC image capture.</details> 4545 <tag id="BC" /> 4546 </entry> 4547 <entry name="thumbnailQuality" type="byte" visibility="public" hwlevel="legacy"> 4548 <description>Compression quality of JPEG 4549 thumbnail.</description> 4550 <range>1-100; larger is higher quality</range> 4551 <details>This tag is also used to describe the quality of the HEIC image capture.</details> 4552 <tag id="BC" /> 4553 </entry> 4554 <entry name="thumbnailSize" type="int32" visibility="public" 4555 container="array" typedef="size" hwlevel="legacy"> 4556 <array> 4557 <size>2</size> 4558 </array> 4559 <description>Resolution of embedded JPEG thumbnail.</description> 4560 <range>android.jpeg.availableThumbnailSizes</range> 4561 <details>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, 4562 but the captured JPEG will still be a valid image. 4563 4564 For best results, when issuing a request for a JPEG image, the thumbnail size selected 4565 should have the same aspect ratio as the main JPEG output. 4566 4567 If the thumbnail image aspect ratio differs from the JPEG primary image aspect 4568 ratio, the camera device creates the thumbnail by cropping it from the primary image. 4569 For example, if the primary image has 4:3 aspect ratio, the thumbnail image has 4570 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to 4571 generate the thumbnail image. The thumbnail image will always have a smaller Field 4572 Of View (FOV) than the primary image when aspect ratios differ. 4573 4574 When an android.jpeg.orientation of non-zero degree is requested, 4575 the camera device will handle thumbnail rotation in one of the following ways: 4576 4577 * Set the {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag} 4578 and keep jpeg and thumbnail image data unrotated. 4579 * Rotate the jpeg and thumbnail image data and not set 4580 {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}. In this 4581 case, LIMITED or FULL hardware level devices will report rotated thumbnail size in 4582 capture result, so the width and height will be interchanged if 90 or 270 degree 4583 orientation is requested. LEGACY device will always report unrotated thumbnail 4584 size. 4585 4586 The tag is also used as thumbnail size for HEIC image format capture, in which case the 4587 the thumbnail rotation is reflected by 4588 {@link android.media.ExifInterface#TAG_ORIENTATION EXIF orientation flag}, and not by 4589 rotating the thumbnail data itself. 4590 </details> 4591 <hal_details> 4592 The HAL must not squeeze or stretch the downscaled primary image to generate thumbnail. 4593 The cropping must be done on the primary jpeg image rather than the sensor pre-correction 4594 active array. The stream cropping rule specified by "S5. Cropping" in camera3.h doesn't 4595 apply to the thumbnail image cropping. 4596 </hal_details> 4597 <tag id="BC" /> 4598 </entry> 4599 </controls> 4600 <static> 4601 <entry name="availableThumbnailSizes" type="int32" visibility="public" 4602 container="array" typedef="size" hwlevel="legacy"> 4603 <array> 4604 <size>2</size> 4605 <size>n</size> 4606 </array> 4607 <description>List of JPEG thumbnail sizes for android.jpeg.thumbnailSize supported by this 4608 camera device.</description> 4609 <details> 4610 This list will include at least one non-zero resolution, plus `(0,0)` for indicating no 4611 thumbnail should be generated. 4612 4613 Below conditions will be satisfied for this size list: 4614 4615 * The sizes will be sorted by increasing pixel area (width x height). 4616 If several resolutions have the same area, they will be sorted by increasing width. 4617 * The aspect ratio of the largest thumbnail size will be same as the 4618 aspect ratio of largest JPEG output size in android.scaler.availableStreamConfigurations. 4619 The largest size is defined as the size that has the largest pixel area 4620 in a given size list. 4621 * Each output JPEG size in android.scaler.availableStreamConfigurations will have at least 4622 one corresponding size that has the same aspect ratio in availableThumbnailSizes, 4623 and vice versa. 4624 * All non-`(0, 0)` sizes will have non-zero widths and heights. 4625 4626 This list is also used as supported thumbnail sizes for HEIC image format capture. 4627 </details> 4628 <tag id="BC" /> 4629 </entry> 4630 <entry name="maxSize" type="int32" visibility="system"> 4631 <description>Maximum size in bytes for the compressed 4632 JPEG buffer, in default sensor pixel mode (see android.sensor.pixelMode)</description> 4633 <range>Must be large enough to fit any JPEG produced by 4634 the camera</range> 4635 <details>This is used for sizing the gralloc buffers for 4636 JPEG</details> 4637 </entry> 4638 </static> 4639 <dynamic> 4640 <clone entry="android.jpeg.gpsLocation" kind="controls"> 4641 </clone> 4642 <clone entry="android.jpeg.gpsCoordinates" kind="controls"> 4643 </clone> 4644 <clone entry="android.jpeg.gpsProcessingMethod" 4645 kind="controls"></clone> 4646 <clone entry="android.jpeg.gpsTimestamp" kind="controls"> 4647 </clone> 4648 <clone entry="android.jpeg.orientation" kind="controls"> 4649 </clone> 4650 <clone entry="android.jpeg.quality" kind="controls"> 4651 </clone> 4652 <entry name="size" type="int32"> 4653 <description>The size of the compressed JPEG image, in 4654 bytes</description> 4655 <range>&gt;= 0</range> 4656 <details>If no JPEG output is produced for the request, 4657 this must be 0. 4658 4659 Otherwise, this describes the real size of the compressed 4660 JPEG image placed in the output stream. More specifically, 4661 if android.jpeg.maxSize = 1000000, and a specific capture 4662 has android.jpeg.size = 500000, then the output buffer from 4663 the JPEG stream will be 1000000 bytes, of which the first 4664 500000 make up the real data.</details> 4665 <tag id="FUTURE" /> 4666 </entry> 4667 <clone entry="android.jpeg.thumbnailQuality" 4668 kind="controls"></clone> 4669 <clone entry="android.jpeg.thumbnailSize" kind="controls"> 4670 </clone> 4671 </dynamic> 4672 </section> 4673 <section name="lens"> 4674 <controls> 4675 <entry name="aperture" type="float" visibility="public" hwlevel="full"> 4676 <description>The desired lens aperture size, as a ratio of lens focal length to the 4677 effective aperture diameter.</description> 4678 <units>The f-number (f/N)</units> 4679 <range>android.lens.info.availableApertures</range> 4680 <details>Setting this value is only supported on the camera devices that have a variable 4681 aperture lens. 4682 4683 When this is supported and android.control.aeMode is OFF, 4684 this can be set along with android.sensor.exposureTime, 4685 android.sensor.sensitivity, and android.sensor.frameDuration 4686 to achieve manual exposure control. 4687 4688 The requested aperture value may take several frames to reach the 4689 requested value; the camera device will report the current (intermediate) 4690 aperture size in capture result metadata while the aperture is changing. 4691 While the aperture is still changing, android.lens.state will be set to MOVING. 4692 4693 When this is supported and android.control.aeMode is one of 4694 the ON modes, this will be overridden by the camera device 4695 auto-exposure algorithm, the overridden values are then provided 4696 back to the user in the corresponding result.</details> 4697 <tag id="V1" /> 4698 </entry> 4699 <entry name="filterDensity" type="float" visibility="public" hwlevel="full"> 4700 <description> 4701 The desired setting for the lens neutral density filter(s). 4702 </description> 4703 <units>Exposure Value (EV)</units> 4704 <range>android.lens.info.availableFilterDensities</range> 4705 <details> 4706 This control will not be supported on most camera devices. 4707 4708 Lens filters are typically used to lower the amount of light the 4709 sensor is exposed to (measured in steps of EV). As used here, an EV 4710 step is the standard logarithmic representation, which are 4711 non-negative, and inversely proportional to the amount of light 4712 hitting the sensor. For example, setting this to 0 would result 4713 in no reduction of the incoming light, and setting this to 2 would 4714 mean that the filter is set to reduce incoming light by two stops 4715 (allowing 1/4 of the prior amount of light to the sensor). 4716 4717 It may take several frames before the lens filter density changes 4718 to the requested value. While the filter density is still changing, 4719 android.lens.state will be set to MOVING. 4720 </details> 4721 <tag id="V1" /> 4722 </entry> 4723 <entry name="focalLength" type="float" visibility="public" hwlevel="legacy"> 4724 <description> 4725 The desired lens focal length; used for optical zoom. 4726 </description> 4727 <units>Millimeters</units> 4728 <range>android.lens.info.availableFocalLengths</range> 4729 <details> 4730 This setting controls the physical focal length of the camera 4731 device's lens. Changing the focal length changes the field of 4732 view of the camera device, and is usually used for optical zoom. 4733 4734 Like android.lens.focusDistance and android.lens.aperture, this 4735 setting won't be applied instantaneously, and it may take several 4736 frames before the lens can change to the requested focal length. 4737 While the focal length is still changing, android.lens.state will 4738 be set to MOVING. 4739 4740 Optical zoom via this control will not be supported on most devices. Starting from API 4741 level 30, the camera device may combine optical and digital zoom through the 4742 android.control.zoomRatio control. 4743 </details> 4744 <hal_details> 4745 For a logical camera device supporting both optical and digital zoom, if focalLength and 4746 cropRegion change in the same request, the camera device must make sure that the new 4747 focalLength and cropRegion take effect in the same frame. This is to make sure that there 4748 is no visible field-of-view jump during zoom. For example, if cropRegion is applied 4749 immediately, but focalLength takes more than 1 frame to take effect, the camera device 4750 will delay the cropRegion so that it's synchronized with focalLength. 4751 4752 Starting from API level 30, it's strongly recommended for HAL to implement the 4753 combination of optical and digital zoom using the new android.control.zoomRatio API, in 4754 lieu of using android.lens.focalLength and android.scaler.cropRegion. 4755 </hal_details> 4756 <tag id="V1" /> 4757 </entry> 4758 <entry name="focusDistance" type="float" visibility="public" hwlevel="full"> 4759 <description>Desired distance to plane of sharpest focus, 4760 measured from frontmost surface of the lens.</description> 4761 <units>See android.lens.info.focusDistanceCalibration for details</units> 4762 <range>&gt;= 0</range> 4763 <details> 4764 This control can be used for setting manual focus, on devices that support 4765 the MANUAL_SENSOR capability and have a variable-focus lens (see 4766 android.lens.info.minimumFocusDistance). 4767 4768 A value of `0.0f` means infinity focus. The value set will be clamped to 4769 `[0.0f, android.lens.info.minimumFocusDistance]`. 4770 4771 Like android.lens.focalLength, this setting won't be applied 4772 instantaneously, and it may take several frames before the lens 4773 can move to the requested focus distance. While the lens is still moving, 4774 android.lens.state will be set to MOVING. 4775 4776 LEGACY devices support at most setting this to `0.0f` 4777 for infinity focus. 4778 </details> 4779 <tag id="BC" /> 4780 <tag id="V1" /> 4781 </entry> 4782 <entry name="opticalStabilizationMode" type="byte" visibility="public" 4783 enum="true" hwlevel="limited"> 4784 <enum> 4785 <value>OFF 4786 <notes>Optical stabilization is unavailable.</notes> 4787 </value> 4788 <value optional="true">ON 4789 <notes>Optical stabilization is enabled.</notes> 4790 </value> 4791 </enum> 4792 <description> 4793 Sets whether the camera device uses optical image stabilization (OIS) 4794 when capturing images. 4795 </description> 4796 <range>android.lens.info.availableOpticalStabilization</range> 4797 <details> 4798 OIS is used to compensate for motion blur due to small 4799 movements of the camera during capture. Unlike digital image 4800 stabilization (android.control.videoStabilizationMode), OIS 4801 makes use of mechanical elements to stabilize the camera 4802 sensor, and thus allows for longer exposure times before 4803 camera shake becomes apparent. 4804 4805 Switching between different optical stabilization modes may take several 4806 frames to initialize, the camera device will report the current mode in 4807 capture result metadata. For example, When "ON" mode is requested, the 4808 optical stabilization modes in the first several capture results may still 4809 be "OFF", and it will become "ON" when the initialization is done. 4810 4811 If a camera device supports both OIS and digital image stabilization 4812 (android.control.videoStabilizationMode), turning both modes on may produce undesirable 4813 interaction, so it is recommended not to enable both at the same time. 4814 4815 If android.control.videoStabilizationMode is set to "PREVIEW_STABILIZATION", 4816 android.lens.opticalStabilizationMode is overridden. The camera sub-system may choose 4817 to turn on hardware based image stabilization in addition to software based stabilization 4818 if it deems that appropriate. This key's value in the capture result will reflect which 4819 OIS mode was chosen. 4820 4821 Not all devices will support OIS; see 4822 android.lens.info.availableOpticalStabilization for 4823 available controls. 4824 </details> 4825 <tag id="V1" /> 4826 </entry> 4827 </controls> 4828 <static> 4829 <namespace name="info"> 4830 <entry name="availableApertures" type="float" visibility="public" 4831 container="array" hwlevel="full"> 4832 <array> 4833 <size>n</size> 4834 </array> 4835 <description>List of aperture size values for android.lens.aperture that are 4836 supported by this camera device.</description> 4837 <units>The aperture f-number</units> 4838 <details>If the camera device doesn't support a variable lens aperture, 4839 this list will contain only one value, which is the fixed aperture size. 4840 4841 If the camera device supports a variable aperture, the aperture values 4842 in this list will be sorted in ascending order.</details> 4843 <tag id="V1" /> 4844 </entry> 4845 <entry name="availableFilterDensities" type="float" visibility="public" 4846 container="array" hwlevel="full"> 4847 <array> 4848 <size>n</size> 4849 </array> 4850 <description> 4851 List of neutral density filter values for 4852 android.lens.filterDensity that are supported by this camera device. 4853 </description> 4854 <units>Exposure value (EV)</units> 4855 <range> 4856 Values are &gt;= 0 4857 </range> 4858 <details> 4859 If a neutral density filter is not supported by this camera device, 4860 this list will contain only 0. Otherwise, this list will include every 4861 filter density supported by the camera device, in ascending order. 4862 </details> 4863 <tag id="V1" /> 4864 </entry> 4865 <entry name="availableFocalLengths" type="float" visibility="public" 4866 type_notes="The list of available focal lengths" 4867 container="array" hwlevel="legacy"> 4868 <array> 4869 <size>n</size> 4870 </array> 4871 <description> 4872 List of focal lengths for android.lens.focalLength that are supported by this camera 4873 device. 4874 </description> 4875 <units>Millimeters</units> 4876 <range> 4877 Values are &gt; 0 4878 </range> 4879 <details> 4880 If optical zoom is not supported, this list will only contain 4881 a single value corresponding to the fixed focal length of the 4882 device. Otherwise, this list will include every focal length supported 4883 by the camera device, in ascending order. 4884 </details> 4885 <tag id="BC" /> 4886 <tag id="V1" /> 4887 </entry> 4888 <entry name="availableOpticalStabilization" type="byte" 4889 visibility="public" type_notes="list of enums" container="array" 4890 typedef="enumList" hwlevel="limited"> 4891 <array> 4892 <size>n</size> 4893 </array> 4894 <description> 4895 List of optical image stabilization (OIS) modes for 4896 android.lens.opticalStabilizationMode that are supported by this camera device. 4897 </description> 4898 <range>Any value listed in android.lens.opticalStabilizationMode</range> 4899 <details> 4900 If OIS is not supported by a given camera device, this list will 4901 contain only OFF. 4902 </details> 4903 <tag id="V1" /> 4904 </entry> 4905 <entry name="hyperfocalDistance" type="float" visibility="public" optional="true" 4906 hwlevel="limited" permission_needed="true"> 4907 <description>Hyperfocal distance for this lens.</description> 4908 <units>See android.lens.info.focusDistanceCalibration for details</units> 4909 <range>If lens is fixed focus, &gt;= 0. If lens has focuser unit, the value is 4910 within `(0.0f, android.lens.info.minimumFocusDistance]`</range> 4911 <details> 4912 If the lens is not fixed focus, the camera device will report this 4913 field when android.lens.info.focusDistanceCalibration is APPROXIMATE or CALIBRATED. 4914 </details> 4915 </entry> 4916 <entry name="minimumFocusDistance" type="float" visibility="public" optional="true" 4917 hwlevel="limited" permission_needed="true"> 4918 <description>Shortest distance from frontmost surface 4919 of the lens that can be brought into sharp focus.</description> 4920 <units>See android.lens.info.focusDistanceCalibration for details</units> 4921 <range>&gt;= 0</range> 4922 <details>If the lens is fixed-focus, this will be 4923 0.</details> 4924 <hal_details>Mandatory for FULL devices; LIMITED devices 4925 must always set this value to 0 for fixed-focus; and may omit 4926 the minimum focus distance otherwise. 4927 4928 This field is also mandatory for all devices advertising 4929 the MANUAL_SENSOR capability.</hal_details> 4930 <tag id="V1" /> 4931 </entry> 4932 <entry name="shadingMapSize" type="int32" visibility="ndk_public" 4933 type_notes="width and height (N, M) of lens shading map provided by the camera device." 4934 container="array" typedef="size" hwlevel="full"> 4935 <array> 4936 <size>2</size> 4937 </array> 4938 <description>Dimensions of lens shading map.</description> 4939 <range>Both values &gt;= 1</range> 4940 <details> 4941 The map should be on the order of 30-40 rows and columns, and 4942 must be smaller than 64x64. 4943 </details> 4944 <tag id="V1" /> 4945 </entry> 4946 <entry name="focusDistanceCalibration" type="byte" visibility="public" 4947 enum="true" hwlevel="limited"> 4948 <enum> 4949 <value>UNCALIBRATED 4950 <notes> 4951 The lens focus distance is not accurate, and the units used for 4952 android.lens.focusDistance do not correspond to any physical units. 4953 4954 Setting the lens to the same focus distance on separate occasions may 4955 result in a different real focus distance, depending on factors such 4956 as the orientation of the device, the age of the focusing mechanism, 4957 and the device temperature. The focus distance value will still be 4958 in the range of `[0, android.lens.info.minimumFocusDistance]`, where 0 4959 represents the farthest focus. 4960 </notes> 4961 </value> 4962 <value>APPROXIMATE 4963 <notes> 4964 The lens focus distance is measured in diopters. 4965 4966 However, setting the lens to the same focus distance 4967 on separate occasions may result in a different real 4968 focus distance, depending on factors such as the 4969 orientation of the device, the age of the focusing 4970 mechanism, and the device temperature. 4971 </notes> 4972 </value> 4973 <value>CALIBRATED 4974 <notes> 4975 The lens focus distance is measured in diopters, and 4976 is calibrated. 4977 4978 The lens mechanism is calibrated so that setting the 4979 same focus distance is repeatable on multiple 4980 occasions with good accuracy, and the focus distance 4981 corresponds to the real physical distance to the plane 4982 of best focus. 4983 </notes> 4984 </value> 4985 </enum> 4986 <description>The lens focus distance calibration quality.</description> 4987 <details> 4988 The lens focus distance calibration quality determines the reliability of 4989 focus related metadata entries, i.e. android.lens.focusDistance, 4990 android.lens.focusRange, android.lens.info.hyperfocalDistance, and 4991 android.lens.info.minimumFocusDistance. 4992 4993 APPROXIMATE and CALIBRATED devices report the focus metadata in 4994 units of diopters (1/meter), so `0.0f` represents focusing at infinity, 4995 and increasing positive numbers represent focusing closer and closer 4996 to the camera device. The focus distance control also uses diopters 4997 on these devices. 4998 4999 UNCALIBRATED devices do not use units that are directly comparable 5000 to any real physical measurement, but `0.0f` still represents farthest 5001 focus, and android.lens.info.minimumFocusDistance represents the 5002 nearest focus the device can achieve. 5003 </details> 5004 <hal_details> 5005 For devices advertise APPROXIMATE quality or higher, diopters 0 (infinity 5006 focus) must work. When autofocus is disabled (android.control.afMode == OFF) 5007 and the lens focus distance is set to 0 diopters 5008 (android.lens.focusDistance == 0), the lens will move to focus at infinity 5009 and is stably focused at infinity even if the device tilts. It may take the 5010 lens some time to move; during the move the lens state should be MOVING and 5011 the output diopter value should be changing toward 0. 5012 </hal_details> 5013 <tag id="V1" /> 5014 </entry> 5015 </namespace> 5016 <entry name="facing" type="byte" visibility="public" enum="true" hwlevel="legacy"> 5017 <enum> 5018 <value>FRONT 5019 <notes> 5020 The camera device faces the same direction as the device's screen. 5021 </notes></value> 5022 <value>BACK 5023 <notes> 5024 The camera device faces the opposite direction as the device's screen. 5025 </notes></value> 5026 <value>EXTERNAL 5027 <notes> 5028 The camera device is an external camera, and has no fixed facing relative to the 5029 device's screen. 5030 </notes></value> 5031 </enum> 5032 <description>Direction the camera faces relative to 5033 device screen.</description> 5034 </entry> 5035 <entry name="poseRotation" type="float" visibility="public" 5036 container="array" permission_needed="true"> 5037 <array> 5038 <size>4</size> 5039 </array> 5040 <description> 5041 The orientation of the camera relative to the sensor 5042 coordinate system. 5043 </description> 5044 <units> 5045 Quaternion coefficients 5046 </units> 5047 <details> 5048 The four coefficients that describe the quaternion 5049 rotation from the Android sensor coordinate system to a 5050 camera-aligned coordinate system where the X-axis is 5051 aligned with the long side of the image sensor, the Y-axis 5052 is aligned with the short side of the image sensor, and 5053 the Z-axis is aligned with the optical axis of the sensor. 5054 5055 To convert from the quaternion coefficients `(x,y,z,w)` 5056 to the axis of rotation `(a_x, a_y, a_z)` and rotation 5057 amount `theta`, the following formulas can be used: 5058 5059 theta = 2 * acos(w) 5060 a_x = x / sin(theta/2) 5061 a_y = y / sin(theta/2) 5062 a_z = z / sin(theta/2) 5063 5064 To create a 3x3 rotation matrix that applies the rotation 5065 defined by this quaternion, the following matrix can be 5066 used: 5067 5068 R = [ 1 - 2y^2 - 2z^2, 2xy - 2zw, 2xz + 2yw, 5069 2xy + 2zw, 1 - 2x^2 - 2z^2, 2yz - 2xw, 5070 2xz - 2yw, 2yz + 2xw, 1 - 2x^2 - 2y^2 ] 5071 5072 This matrix can then be used to apply the rotation to a 5073 column vector point with 5074 5075 `p' = Rp` 5076 5077 where `p` is in the device sensor coordinate system, and 5078 `p'` is in the camera-oriented coordinate system. 5079 5080 If android.lens.poseReference is UNDEFINED, the quaternion rotation cannot 5081 be accurately represented by the camera device, and will be represented by 5082 default values matching its default facing. 5083 </details> 5084 <tag id="DEPTH" /> 5085 </entry> 5086 <entry name="poseTranslation" type="float" visibility="public" 5087 container="array" permission_needed="true"> 5088 <array> 5089 <size>3</size> 5090 </array> 5091 <description>Position of the camera optical center.</description> 5092 <units>Meters</units> 5093 <details> 5094 The position of the camera device's lens optical center, 5095 as a three-dimensional vector `(x,y,z)`. 5096 5097 Prior to Android P, or when android.lens.poseReference is PRIMARY_CAMERA, this position 5098 is relative to the optical center of the largest camera device facing in the same 5099 direction as this camera, in the {@link android.hardware.SensorEvent Android sensor 5100 coordinate axes}. Note that only the axis definitions are shared with the sensor 5101 coordinate system, but not the origin. 5102 5103 If this device is the largest or only camera device with a given facing, then this 5104 position will be `(0, 0, 0)`; a camera device with a lens optical center located 3 cm 5105 from the main sensor along the +X axis (to the right from the user's perspective) will 5106 report `(0.03, 0, 0)`. Note that this means that, for many computer vision 5107 applications, the position needs to be negated to convert it to a translation from the 5108 camera to the origin. 5109 5110 To transform a pixel coordinates between two cameras facing the same direction, first 5111 the source camera android.lens.distortion must be corrected for. Then the source 5112 camera android.lens.intrinsicCalibration needs to be applied, followed by the 5113 android.lens.poseRotation of the source camera, the translation of the source camera 5114 relative to the destination camera, the android.lens.poseRotation of the destination 5115 camera, and finally the inverse of android.lens.intrinsicCalibration of the destination 5116 camera. This obtains a radial-distortion-free coordinate in the destination camera pixel 5117 coordinates. 5118 5119 To compare this against a real image from the destination camera, the destination camera 5120 image then needs to be corrected for radial distortion before comparison or sampling. 5121 5122 When android.lens.poseReference is GYROSCOPE, then this position is relative to 5123 the center of the primary gyroscope on the device. The axis definitions are the same as 5124 with PRIMARY_CAMERA. 5125 5126 When android.lens.poseReference is UNDEFINED, this position cannot be accurately 5127 represented by the camera device, and will be represented as `(0, 0, 0)`. 5128 5129 When android.lens.poseReference is AUTOMOTIVE, then this position is relative to the 5130 origin of the automotive sensor coordinate system, which is at the center of the rear 5131 axle. 5132 </details> 5133 <tag id="DEPTH" /> 5134 </entry> 5135 </static> 5136 <dynamic> 5137 <clone entry="android.lens.aperture" kind="controls"> 5138 <tag id="V1" /> 5139 </clone> 5140 <clone entry="android.lens.filterDensity" kind="controls"> 5141 <tag id="V1" /> 5142 </clone> 5143 <clone entry="android.lens.focalLength" kind="controls"> 5144 <tag id="BC" /> 5145 </clone> 5146 <clone entry="android.lens.focusDistance" kind="controls"> 5147 <details>Should be zero for fixed-focus cameras</details> 5148 <tag id="BC" /> 5149 </clone> 5150 <entry name="focusRange" type="float" visibility="public" 5151 type_notes="Range of scene distances that are in focus" 5152 container="array" typedef="pairFloatFloat" hwlevel="limited"> 5153 <array> 5154 <size>2</size> 5155 </array> 5156 <description>The range of scene distances that are in 5157 sharp focus (depth of field).</description> 5158 <units>A pair of focus distances in diopters: (near, 5159 far); see android.lens.info.focusDistanceCalibration for details.</units> 5160 <range>&gt;=0</range> 5161 <details>If variable focus not supported, can still report 5162 fixed depth of field range</details> 5163 <tag id="BC" /> 5164 </entry> 5165 <clone entry="android.lens.opticalStabilizationMode" 5166 kind="controls"> 5167 <tag id="V1" /> 5168 </clone> 5169 <entry name="state" type="byte" visibility="public" enum="true" hwlevel="limited"> 5170 <enum> 5171 <value>STATIONARY 5172 <notes> 5173 The lens parameters (android.lens.focalLength, android.lens.focusDistance, 5174 android.lens.filterDensity and android.lens.aperture) are not changing. 5175 </notes> 5176 </value> 5177 <value>MOVING 5178 <notes> 5179 One or several of the lens parameters 5180 (android.lens.focalLength, android.lens.focusDistance, 5181 android.lens.filterDensity or android.lens.aperture) is 5182 currently changing. 5183 </notes> 5184 </value> 5185 </enum> 5186 <description>Current lens status.</description> 5187 <details> 5188 For lens parameters android.lens.focalLength, android.lens.focusDistance, 5189 android.lens.filterDensity and android.lens.aperture, when changes are requested, 5190 they may take several frames to reach the requested values. This state indicates 5191 the current status of the lens parameters. 5192 5193 When the state is STATIONARY, the lens parameters are not changing. This could be 5194 either because the parameters are all fixed, or because the lens has had enough 5195 time to reach the most recently-requested values. 5196 If all these lens parameters are not changeable for a camera device, as listed below: 5197 5198 * Fixed focus (`android.lens.info.minimumFocusDistance == 0`), which means 5199 android.lens.focusDistance parameter will always be 0. 5200 * Fixed focal length (android.lens.info.availableFocalLengths contains single value), 5201 which means the optical zoom is not supported. 5202 * No ND filter (android.lens.info.availableFilterDensities contains only 0). 5203 * Fixed aperture (android.lens.info.availableApertures contains single value). 5204 5205 Then this state will always be STATIONARY. 5206 5207 When the state is MOVING, it indicates that at least one of the lens parameters 5208 is changing. 5209 </details> 5210 <tag id="V1" /> 5211 </entry> 5212 <clone entry="android.lens.poseRotation" kind="static"> 5213 </clone> 5214 <clone entry="android.lens.poseTranslation" kind="static"> 5215 </clone> 5216 </dynamic> 5217 <static> 5218 <entry name="intrinsicCalibration" type="float" visibility="public" 5219 container="array" permission_needed="true"> 5220 <array> 5221 <size>5</size> 5222 </array> 5223 <description> 5224 The parameters for this camera device's intrinsic 5225 calibration. 5226 </description> 5227 <units> 5228 Pixels in the 5229 android.sensor.info.preCorrectionActiveArraySize 5230 coordinate system. 5231 </units> 5232 <details> 5233 The five calibration parameters that describe the 5234 transform from camera-centric 3D coordinates to sensor 5235 pixel coordinates: 5236 5237 [f_x, f_y, c_x, c_y, s] 5238 5239 Where `f_x` and `f_y` are the horizontal and vertical 5240 focal lengths, `[c_x, c_y]` is the position of the optical 5241 axis, and `s` is a skew parameter for the sensor plane not 5242 being aligned with the lens plane. 5243 5244 These are typically used within a transformation matrix K: 5245 5246 K = [ f_x, s, c_x, 5247 0, f_y, c_y, 5248 0 0, 1 ] 5249 5250 which can then be combined with the camera pose rotation 5251 `R` and translation `t` (android.lens.poseRotation and 5252 android.lens.poseTranslation, respectively) to calculate the 5253 complete transform from world coordinates to pixel 5254 coordinates: 5255 5256 P = [ K 0 * [ R -Rt 5257 0 1 ] 0 1 ] 5258 5259 (Note the negation of poseTranslation when mapping from camera 5260 to world coordinates, and multiplication by the rotation). 5261 5262 With `p_w` being a point in the world coordinate system 5263 and `p_s` being a point in the camera active pixel array 5264 coordinate system, and with the mapping including the 5265 homogeneous division by z: 5266 5267 p_h = (x_h, y_h, z_h) = P p_w 5268 p_s = p_h / z_h 5269 5270 so `[x_s, y_s]` is the pixel coordinates of the world 5271 point, `z_s = 1`, and `w_s` is a measurement of disparity 5272 (depth) in pixel coordinates. 5273 5274 Note that the coordinate system for this transform is the 5275 android.sensor.info.preCorrectionActiveArraySize system, 5276 where `(0,0)` is the top-left of the 5277 preCorrectionActiveArraySize rectangle. Once the pose and 5278 intrinsic calibration transforms have been applied to a 5279 world point, then the android.lens.distortion 5280 transform needs to be applied, and the result adjusted to 5281 be in the android.sensor.info.activeArraySize coordinate 5282 system (where `(0, 0)` is the top-left of the 5283 activeArraySize rectangle), to determine the final pixel 5284 coordinate of the world point for processed (non-RAW) 5285 output buffers. 5286 5287 For camera devices, the center of pixel `(x,y)` is located at 5288 coordinate `(x + 0.5, y + 0.5)`. So on a device with a 5289 precorrection active array of size `(10,10)`, the valid pixel 5290 indices go from `(0,0)-(9,9)`, and an perfectly-built camera would 5291 have an optical center at the exact center of the pixel grid, at 5292 coordinates `(5.0, 5.0)`, which is the top-left corner of pixel 5293 `(5,5)`. 5294 </details> 5295 <tag id="DEPTH" /> 5296 </entry> 5297 <entry name="radialDistortion" type="float" visibility="public" 5298 deprecated="true" container="array" permission_needed="true"> 5299 <array> 5300 <size>6</size> 5301 </array> 5302 <description> 5303 The correction coefficients to correct for this camera device's 5304 radial and tangential lens distortion. 5305 </description> 5306 <deprecation_description> 5307 This field was inconsistently defined in terms of its 5308 normalization. Use android.lens.distortion instead. 5309 </deprecation_description> 5310 <units> 5311 Unitless coefficients. 5312 </units> 5313 <details> 5314 Four radial distortion coefficients `[kappa_0, kappa_1, kappa_2, 5315 kappa_3]` and two tangential distortion coefficients 5316 `[kappa_4, kappa_5]` that can be used to correct the 5317 lens's geometric distortion with the mapping equations: 5318 5319 x_c = x_i * ( kappa_0 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 5320 kappa_4 * (2 * x_i * y_i) + kappa_5 * ( r^2 + 2 * x_i^2 ) 5321 y_c = y_i * ( kappa_0 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 5322 kappa_5 * (2 * x_i * y_i) + kappa_4 * ( r^2 + 2 * y_i^2 ) 5323 5324 Here, `[x_c, y_c]` are the coordinates to sample in the 5325 input image that correspond to the pixel values in the 5326 corrected image at the coordinate `[x_i, y_i]`: 5327 5328 correctedImage(x_i, y_i) = sample_at(x_c, y_c, inputImage) 5329 5330 The pixel coordinates are defined in a normalized 5331 coordinate system related to the 5332 android.lens.intrinsicCalibration calibration fields. 5333 Both `[x_i, y_i]` and `[x_c, y_c]` have `(0,0)` at the 5334 lens optical center `[c_x, c_y]`. The maximum magnitudes 5335 of both x and y coordinates are normalized to be 1 at the 5336 edge further from the optical center, so the range 5337 for both dimensions is `-1 <= x <= 1`. 5338 5339 Finally, `r` represents the radial distance from the 5340 optical center, `r^2 = x_i^2 + y_i^2`, and its magnitude 5341 is therefore no larger than `|r| <= sqrt(2)`. 5342 5343 The distortion model used is the Brown-Conrady model. 5344 </details> 5345 <tag id="DEPTH" /> 5346 </entry> 5347 </static> 5348 <dynamic> 5349 <clone entry="android.lens.intrinsicCalibration" kind="static"> 5350 </clone> 5351 <clone entry="android.lens.radialDistortion" kind="static"> 5352 </clone> 5353 </dynamic> 5354 <static> 5355 <entry name="poseReference" type="byte" visibility="public" enum="true" 5356 permission_needed="true" hal_version="3.3" > 5357 <enum> 5358 <value>PRIMARY_CAMERA 5359 <notes>The value of android.lens.poseTranslation is relative to the optical center of 5360 the largest camera device facing the same direction as this camera. 5361 5362 This is the default value for API levels before Android P. 5363 </notes> 5364 </value> 5365 <value>GYROSCOPE 5366 <notes>The value of android.lens.poseTranslation is relative to the position of the 5367 primary gyroscope of this Android device. 5368 </notes> 5369 </value> 5370 <value hal_version="3.5">UNDEFINED 5371 <notes>The camera device cannot represent the values of android.lens.poseTranslation 5372 and android.lens.poseRotation accurately enough. One such example is a camera device 5373 on the cover of a foldable phone: in order to measure the pose translation and rotation, 5374 some kind of hinge position sensor would be needed. 5375 5376 The value of android.lens.poseTranslation must be all zeros, and 5377 android.lens.poseRotation must be values matching its default facing. 5378 </notes> 5379 </value> 5380 <value hal_version="3.8">AUTOMOTIVE 5381 <notes>The value of android.lens.poseTranslation is relative to the origin of the 5382 automotive sensor coordinate system, which is at the center of the rear axle. 5383 </notes> 5384 </value> 5385 </enum> 5386 <description> 5387 The origin for android.lens.poseTranslation, and the accuracy of 5388 android.lens.poseTranslation and android.lens.poseRotation. 5389 </description> 5390 <details> 5391 Different calibration methods and use cases can produce better or worse results 5392 depending on the selected coordinate origin. 5393 </details> 5394 </entry> 5395 <entry name="distortion" type="float" visibility="public" container="array" 5396 permission_needed="true" hal_version="3.3" > 5397 <array> 5398 <size>5</size> 5399 </array> 5400 <description> 5401 The correction coefficients to correct for this camera device's 5402 radial and tangential lens distortion. 5403 5404 Replaces the deprecated android.lens.radialDistortion field, which was 5405 inconsistently defined. 5406 </description> 5407 <units> 5408 Unitless coefficients. 5409 </units> 5410 <details> 5411 Three radial distortion coefficients `[kappa_1, kappa_2, 5412 kappa_3]` and two tangential distortion coefficients 5413 `[kappa_4, kappa_5]` that can be used to correct the 5414 lens's geometric distortion with the mapping equations: 5415 5416 x_c = x_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 5417 kappa_4 * (2 * x_i * y_i) + kappa_5 * ( r^2 + 2 * x_i^2 ) 5418 y_c = y_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) + 5419 kappa_5 * (2 * x_i * y_i) + kappa_4 * ( r^2 + 2 * y_i^2 ) 5420 5421 Here, `[x_c, y_c]` are the coordinates to sample in the 5422 input image that correspond to the pixel values in the 5423 corrected image at the coordinate `[x_i, y_i]`: 5424 5425 correctedImage(x_i, y_i) = sample_at(x_c, y_c, inputImage) 5426 5427 The pixel coordinates are defined in a coordinate system 5428 related to the android.lens.intrinsicCalibration 5429 calibration fields; see that entry for details of the mapping stages. 5430 Both `[x_i, y_i]` and `[x_c, y_c]` 5431 have `(0,0)` at the lens optical center `[c_x, c_y]`, and 5432 the range of the coordinates depends on the focal length 5433 terms of the intrinsic calibration. 5434 5435 Finally, `r` represents the radial distance from the 5436 optical center, `r^2 = x_i^2 + y_i^2`. 5437 5438 The distortion model used is the Brown-Conrady model. 5439 </details> 5440 <tag id="DEPTH" /> 5441 </entry> 5442 <entry name="distortionMaximumResolution" type="float" visibility="public" container="array" 5443 permission_needed="true" hal_version="3.6" > 5444 <array> 5445 <size>5</size> 5446 </array> 5447 <description> 5448 The correction coefficients to correct for this camera device's 5449 radial and tangential lens distortion for a 5450 CaptureRequest with android.sensor.pixelMode set to 5451 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 5452 </description> 5453 <units> 5454 Unitless coefficients. 5455 </units> 5456 <details> 5457 Analogous to android.lens.distortion, when android.sensor.pixelMode is set to 5458 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 5459 </details> 5460 <tag id="DEPTH" /> 5461 </entry> 5462 <entry name="intrinsicCalibrationMaximumResolution" type="float" visibility="public" 5463 container="array" permission_needed="true" hal_version="3.6"> 5464 <array> 5465 <size>5</size> 5466 </array> 5467 <description> 5468 The parameters for this camera device's intrinsic 5469 calibration when android.sensor.pixelMode is set to 5470 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 5471 </description> 5472 <units> 5473 Pixels in the 5474 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution 5475 coordinate system. 5476 </units> 5477 <details> 5478 Analogous to android.lens.intrinsicCalibration, when android.sensor.pixelMode is set to 5479 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 5480 </details> 5481 <tag id="DEPTH" /> 5482 </entry> 5483 </static> 5484 <dynamic> 5485 <clone entry="android.lens.distortion" kind="static"> 5486 </clone> 5487 </dynamic> 5488 </section> 5489 <section name="noiseReduction"> 5490 <controls> 5491 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 5492 <enum> 5493 <value>OFF 5494 <notes>No noise reduction is applied.</notes></value> 5495 <value>FAST 5496 <notes>Noise reduction is applied without reducing frame rate relative to sensor 5497 output. It may be the same as OFF if noise reduction will reduce frame rate 5498 relative to sensor.</notes></value> 5499 <value>HIGH_QUALITY 5500 <notes>High-quality noise reduction is applied, at the cost of possibly reduced frame 5501 rate relative to sensor output.</notes></value> 5502 <value optional="true">MINIMAL 5503 <notes>MINIMAL noise reduction is applied without reducing frame rate relative to 5504 sensor output. </notes></value> 5505 <value optional="true">ZERO_SHUTTER_LAG 5506 5507 <notes>Noise reduction is applied at different levels for different output streams, 5508 based on resolution. Streams at maximum recording resolution (see {@link 5509 android.hardware.camera2.CameraDevice#createCaptureSession|ACameraDevice_createCaptureSession}) 5510 or below have noise reduction applied, while higher-resolution streams have MINIMAL (if 5511 supported) or no noise reduction applied (if MINIMAL is not supported.) The degree of 5512 noise reduction for low-resolution streams is tuned so that frame rate is not impacted, 5513 and the quality is equal to or better than FAST (since it is only applied to 5514 lower-resolution outputs, quality may improve from FAST). 5515 5516 This mode is intended to be used by applications operating in a zero-shutter-lag mode 5517 with YUV or PRIVATE reprocessing, where the application continuously captures 5518 high-resolution intermediate buffers into a circular buffer, from which a final image is 5519 produced via reprocessing when a user takes a picture. For such a use case, the 5520 high-resolution buffers must not have noise reduction applied to maximize efficiency of 5521 preview and to avoid over-applying noise filtering when reprocessing, while 5522 low-resolution buffers (used for recording or preview, generally) need noise reduction 5523 applied for reasonable preview quality. 5524 5525 This mode is guaranteed to be supported by devices that support either the 5526 YUV_REPROCESSING or PRIVATE_REPROCESSING capabilities 5527 (android.request.availableCapabilities lists either of those capabilities) and it will 5528 be the default mode for CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template. 5529 </notes></value> 5530 </enum> 5531 <description>Mode of operation for the noise reduction algorithm.</description> 5532 <range>android.noiseReduction.availableNoiseReductionModes</range> 5533 <details>The noise reduction algorithm attempts to improve image quality by removing 5534 excessive noise added by the capture process, especially in dark conditions. 5535 5536 OFF means no noise reduction will be applied by the camera device, for both raw and 5537 YUV domain. 5538 5539 MINIMAL means that only sensor raw domain basic noise reduction is enabled ,to remove 5540 demosaicing or other processing artifacts. For YUV_REPROCESSING, MINIMAL is same as OFF. 5541 This mode is optional, may not be support by all devices. The application should check 5542 android.noiseReduction.availableNoiseReductionModes before using it. 5543 5544 FAST/HIGH_QUALITY both mean camera device determined noise filtering 5545 will be applied. HIGH_QUALITY mode indicates that the camera device 5546 will use the highest-quality noise filtering algorithms, 5547 even if it slows down capture rate. FAST means the camera device will not 5548 slow down capture rate when applying noise filtering. FAST may be the same as MINIMAL if 5549 MINIMAL is listed, or the same as OFF if any noise filtering will slow down capture rate. 5550 Every output stream will have a similar amount of enhancement applied. 5551 5552 ZERO_SHUTTER_LAG is meant to be used by applications that maintain a continuous circular 5553 buffer of high-resolution images during preview and reprocess image(s) from that buffer 5554 into a final capture when triggered by the user. In this mode, the camera device applies 5555 noise reduction to low-resolution streams (below maximum recording resolution) to maximize 5556 preview quality, but does not apply noise reduction to high-resolution streams, since 5557 those will be reprocessed later if necessary. 5558 5559 For YUV_REPROCESSING, these FAST/HIGH_QUALITY modes both mean that the camera device 5560 will apply FAST/HIGH_QUALITY YUV domain noise reduction, respectively. The camera device 5561 may adjust the noise reduction parameters for best image quality based on the 5562 android.reprocess.effectiveExposureFactor if it is set. 5563 </details> 5564 <hal_details> 5565 For YUV_REPROCESSING The HAL can use android.reprocess.effectiveExposureFactor to 5566 adjust the internal noise reduction parameters appropriately to get the best quality 5567 images. 5568 </hal_details> 5569 <tag id="V1" /> 5570 <tag id="REPROC" /> 5571 </entry> 5572 <entry name="strength" type="byte"> 5573 <description>Control the amount of noise reduction 5574 applied to the images</description> 5575 <units>1-10; 10 is max noise reduction</units> 5576 <range>1 - 10</range> 5577 <tag id="FUTURE" /> 5578 </entry> 5579 </controls> 5580 <static> 5581 <entry name="availableNoiseReductionModes" type="byte" visibility="public" 5582 type_notes="list of enums" container="array" typedef="enumList" hwlevel="limited"> 5583 <array> 5584 <size>n</size> 5585 </array> 5586 <description> 5587 List of noise reduction modes for android.noiseReduction.mode that are supported 5588 by this camera device. 5589 </description> 5590 <range>Any value listed in android.noiseReduction.mode</range> 5591 <details> 5592 Full-capability camera devices will always support OFF and FAST. 5593 5594 Camera devices that support YUV_REPROCESSING or PRIVATE_REPROCESSING will support 5595 ZERO_SHUTTER_LAG. 5596 5597 Legacy-capability camera devices will only support FAST mode. 5598 </details> 5599 <hal_details> 5600 HAL must support both FAST and HIGH_QUALITY if noise reduction control is available 5601 on the camera device, but the underlying implementation can be the same for both modes. 5602 That is, if the highest quality implementation on the camera device does not slow down 5603 capture rate, then FAST and HIGH_QUALITY will generate the same output. 5604 </hal_details> 5605 <tag id="V1" /> 5606 <tag id="REPROC" /> 5607 </entry> 5608 </static> 5609 <dynamic> 5610 <clone entry="android.noiseReduction.mode" kind="controls"> 5611 <tag id="V1" /> 5612 <tag id="REPROC" /> 5613 </clone> 5614 </dynamic> 5615 </section> 5616 <section name="quirks"> 5617 <static> 5618 <entry name="meteringCropRegion" type="byte" visibility="system" deprecated="true" optional="true"> 5619 <description>If set to 1, the camera service does not 5620 scale 'normalized' coordinates with respect to the crop 5621 region. This applies to metering input (a{e,f,wb}Region 5622 and output (face rectangles).</description> 5623 <deprecation_description> 5624 Not used in HALv3 or newer 5625 </deprecation_description> 5626 <details>Normalized coordinates refer to those in the 5627 (-1000,1000) range mentioned in the 5628 android.hardware.Camera API. 5629 5630 HAL implementations should instead always use and emit 5631 sensor array-relative coordinates for all region data. Does 5632 not need to be listed in static metadata. Support will be 5633 removed in future versions of camera service.</details> 5634 </entry> 5635 <entry name="triggerAfWithAuto" type="byte" visibility="system" deprecated="true" optional="true"> 5636 <description>If set to 1, then the camera service always 5637 switches to FOCUS_MODE_AUTO before issuing a AF 5638 trigger.</description> 5639 <deprecation_description> 5640 Not used in HALv3 or newer 5641 </deprecation_description> 5642 <details>HAL implementations should implement AF trigger 5643 modes for AUTO, MACRO, CONTINUOUS_FOCUS, and 5644 CONTINUOUS_PICTURE modes instead of using this flag. Does 5645 not need to be listed in static metadata. Support will be 5646 removed in future versions of camera service</details> 5647 </entry> 5648 <entry name="useZslFormat" type="byte" visibility="system" deprecated="true" optional="true"> 5649 <description>If set to 1, the camera service uses 5650 CAMERA2_PIXEL_FORMAT_ZSL instead of 5651 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED for the zero 5652 shutter lag stream</description> 5653 <deprecation_description> 5654 Not used in HALv3 or newer 5655 </deprecation_description> 5656 <details>HAL implementations should use gralloc usage flags 5657 to determine that a stream will be used for 5658 zero-shutter-lag, instead of relying on an explicit 5659 format setting. Does not need to be listed in static 5660 metadata. Support will be removed in future versions of 5661 camera service.</details> 5662 </entry> 5663 <entry name="usePartialResult" type="byte" visibility="hidden" deprecated="true" optional="true"> 5664 <description> 5665 If set to 1, the HAL will always split result 5666 metadata for a single capture into multiple buffers, 5667 returned using multiple process_capture_result calls. 5668 </description> 5669 <deprecation_description> 5670 Not used in HALv3 or newer; replaced by better partials mechanism 5671 </deprecation_description> 5672 <details> 5673 Does not need to be listed in static 5674 metadata. Support for partial results will be reworked in 5675 future versions of camera service. This quirk will stop 5676 working at that point; DO NOT USE without careful 5677 consideration of future support. 5678 </details> 5679 <hal_details> 5680 Refer to `camera3_capture_result::partial_result` 5681 for information on how to implement partial results. 5682 </hal_details> 5683 </entry> 5684 </static> 5685 <dynamic> 5686 <entry name="partialResult" type="byte" visibility="hidden" deprecated="true" optional="true" enum="true" typedef="boolean"> 5687 <enum> 5688 <value>FINAL 5689 <notes>The last or only metadata result buffer 5690 for this capture.</notes> 5691 </value> 5692 <value>PARTIAL 5693 <notes>A partial buffer of result metadata for this 5694 capture. More result buffers for this capture will be sent 5695 by the camera device, the last of which will be marked 5696 FINAL.</notes> 5697 </value> 5698 </enum> 5699 <description> 5700 Whether a result given to the framework is the 5701 final one for the capture, or only a partial that contains a 5702 subset of the full set of dynamic metadata 5703 values.</description> 5704 <deprecation_description> 5705 Not used in HALv3 or newer 5706 </deprecation_description> 5707 <range>Optional. Default value is FINAL.</range> 5708 <details> 5709 The entries in the result metadata buffers for a 5710 single capture may not overlap, except for this entry. The 5711 FINAL buffers must retain FIFO ordering relative to the 5712 requests that generate them, so the FINAL buffer for frame 3 must 5713 always be sent to the framework after the FINAL buffer for frame 2, and 5714 before the FINAL buffer for frame 4. PARTIAL buffers may be returned 5715 in any order relative to other frames, but all PARTIAL buffers for a given 5716 capture must arrive before the FINAL buffer for that capture. This entry may 5717 only be used by the camera device if quirks.usePartialResult is set to 1. 5718 </details> 5719 <hal_details> 5720 Refer to `camera3_capture_result::partial_result` 5721 for information on how to implement partial results. 5722 </hal_details> 5723 </entry> 5724 </dynamic> 5725 </section> 5726 <section name="request"> 5727 <controls> 5728 <entry name="frameCount" type="int32" visibility="system" deprecated="true"> 5729 <description>A frame counter set by the framework. Must 5730 be maintained unchanged in output frame. This value monotonically 5731 increases with every new result (that is, each new result has a unique 5732 frameCount value). 5733 </description> 5734 <deprecation_description> 5735 Not used in HALv3 or newer 5736 </deprecation_description> 5737 <units>incrementing integer</units> 5738 <range>Any int.</range> 5739 </entry> 5740 <entry name="id" type="int32" visibility="hidden"> 5741 <description>An application-specified ID for the current 5742 request. Must be maintained unchanged in output 5743 frame</description> 5744 <units>arbitrary integer assigned by application</units> 5745 <range>Any int</range> 5746 <tag id="V1" /> 5747 </entry> 5748 <entry name="inputStreams" type="int32" visibility="system" deprecated="true" 5749 container="array"> 5750 <array> 5751 <size>n</size> 5752 </array> 5753 <description>List which camera reprocess stream is used 5754 for the source of reprocessing data.</description> 5755 <deprecation_description> 5756 Not used in HALv3 or newer 5757 </deprecation_description> 5758 <units>List of camera reprocess stream IDs</units> 5759 <range> 5760 Typically, only one entry allowed, must be a valid reprocess stream ID. 5761 </range> 5762 <details>Only meaningful when android.request.type == 5763 REPROCESS. Ignored otherwise</details> 5764 <tag id="HAL2" /> 5765 </entry> 5766 <entry name="metadataMode" type="byte" visibility="system" 5767 enum="true"> 5768 <enum> 5769 <value>NONE 5770 <notes>No metadata should be produced on output, except 5771 for application-bound buffer data. If no 5772 application-bound streams exist, no frame should be 5773 placed in the output frame queue. If such streams 5774 exist, a frame should be placed on the output queue 5775 with null metadata but with the necessary output buffer 5776 information. Timestamp information should still be 5777 included with any output stream buffers</notes></value> 5778 <value>FULL 5779 <notes>All metadata should be produced. Statistics will 5780 only be produced if they are separately 5781 enabled</notes></value> 5782 </enum> 5783 <description>How much metadata to produce on 5784 output</description> 5785 <tag id="FUTURE" /> 5786 </entry> 5787 <entry name="outputStreams" type="int32" visibility="system" deprecated="true" 5788 container="array"> 5789 <array> 5790 <size>n</size> 5791 </array> 5792 <description>Lists which camera output streams image data 5793 from this capture must be sent to</description> 5794 <deprecation_description> 5795 Not used in HALv3 or newer 5796 </deprecation_description> 5797 <units>List of camera stream IDs</units> 5798 <range>List must only include streams that have been 5799 created</range> 5800 <details>If no output streams are listed, then the image 5801 data should simply be discarded. The image data must 5802 still be captured for metadata and statistics production, 5803 and the lens and flash must operate as requested.</details> 5804 <tag id="HAL2" /> 5805 </entry> 5806 <entry name="type" type="byte" visibility="system" deprecated="true" enum="true"> 5807 <enum> 5808 <value>CAPTURE 5809 <notes>Capture a new image from the imaging hardware, 5810 and process it according to the 5811 settings</notes></value> 5812 <value>REPROCESS 5813 <notes>Process previously captured data; the 5814 android.request.inputStreams parameter determines the 5815 source reprocessing stream. TODO: Mark dynamic metadata 5816 needed for reprocessing with [RP]</notes></value> 5817 </enum> 5818 <description>The type of the request; either CAPTURE or 5819 REPROCESS. For legacy HAL3, this tag is redundant. 5820 </description> 5821 <deprecation_description> 5822 Not used in HALv3 or newer 5823 </deprecation_description> 5824 <tag id="HAL2" /> 5825 </entry> 5826 </controls> 5827 <static> 5828 <entry name="maxNumOutputStreams" type="int32" visibility="ndk_public" 5829 container="array" hwlevel="legacy"> 5830 <array> 5831 <size>3</size> 5832 </array> 5833 <description>The maximum numbers of different types of output streams 5834 that can be configured and used simultaneously by a camera device. 5835 </description> 5836 <range> 5837 For processed (and stalling) format streams, &gt;= 1. 5838 5839 For Raw format (either stalling or non-stalling) streams, &gt;= 0. 5840 5841 For processed (but not stalling) format streams, &gt;= 3 5842 for FULL mode devices (`android.info.supportedHardwareLevel == FULL`); 5843 &gt;= 2 for LIMITED mode devices (`android.info.supportedHardwareLevel == LIMITED`). 5844 </range> 5845 <details> 5846 This is a 3 element tuple that contains the max number of output simultaneous 5847 streams for raw sensor, processed (but not stalling), and processed (and stalling) 5848 formats respectively. For example, assuming that JPEG is typically a processed and 5849 stalling stream, if max raw sensor format output stream number is 1, max YUV streams 5850 number is 3, and max JPEG stream number is 2, then this tuple should be `(1, 3, 2)`. 5851 5852 This lists the upper bound of the number of output streams supported by 5853 the camera device. Using more streams simultaneously may require more hardware and 5854 CPU resources that will consume more power. The image format for an output stream can 5855 be any supported format provided by android.scaler.availableStreamConfigurations. 5856 The formats defined in android.scaler.availableStreamConfigurations can be categorized 5857 into the 3 stream types as below: 5858 5859 * Processed (but stalling): any non-RAW format with a stallDurations &gt; 0. 5860 Typically {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG format}. 5861 * Raw formats: {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16 5862 RAW_SENSOR}, {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10 RAW10}, or 5863 {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12 RAW12}. 5864 * Processed (but not-stalling): any non-RAW format without a stall duration. Typically 5865 {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888 YUV_420_888}, 5866 {@link android.graphics.ImageFormat#NV21 NV21}, {@link 5867 android.graphics.ImageFormat#YV12 YV12}, or {@link 5868 android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} . 5869 </details> 5870 <tag id="BC" /> 5871 </entry> 5872 <entry name="maxNumOutputRaw" type="int32" visibility="java_public" synthetic="true" 5873 hwlevel="legacy"> 5874 <description>The maximum numbers of different types of output streams 5875 that can be configured and used simultaneously by a camera device 5876 for any `RAW` formats. 5877 </description> 5878 <range> 5879 &gt;= 0 5880 </range> 5881 <details> 5882 This value contains the max number of output simultaneous 5883 streams from the raw sensor. 5884 5885 This lists the upper bound of the number of output streams supported by 5886 the camera device. Using more streams simultaneously may require more hardware and 5887 CPU resources that will consume more power. The image format for this kind of an output stream can 5888 be any `RAW` and supported format provided by android.scaler.streamConfigurationMap. 5889 5890 In particular, a `RAW` format is typically one of: 5891 5892 * {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16 RAW_SENSOR} 5893 * {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10 RAW10} 5894 * {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12 RAW12} 5895 5896 LEGACY mode devices (android.info.supportedHardwareLevel `==` LEGACY) 5897 never support raw streams. 5898 </details> 5899 </entry> 5900 <entry name="maxNumOutputProc" type="int32" visibility="java_public" synthetic="true" 5901 hwlevel="legacy"> 5902 <description>The maximum numbers of different types of output streams 5903 that can be configured and used simultaneously by a camera device 5904 for any processed (but not-stalling) formats. 5905 </description> 5906 <range> 5907 &gt;= 3 5908 for FULL mode devices (`android.info.supportedHardwareLevel == FULL`); 5909 &gt;= 2 for LIMITED mode devices (`android.info.supportedHardwareLevel == LIMITED`). 5910 </range> 5911 <details> 5912 This value contains the max number of output simultaneous 5913 streams for any processed (but not-stalling) formats. 5914 5915 This lists the upper bound of the number of output streams supported by 5916 the camera device. Using more streams simultaneously may require more hardware and 5917 CPU resources that will consume more power. The image format for this kind of an output stream can 5918 be any non-`RAW` and supported format provided by android.scaler.streamConfigurationMap. 5919 5920 Processed (but not-stalling) is defined as any non-RAW format without a stall duration. 5921 Typically: 5922 5923 * {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888 YUV_420_888} 5924 * {@link android.graphics.ImageFormat#NV21 NV21} 5925 * {@link android.graphics.ImageFormat#YV12 YV12} 5926 * Implementation-defined formats, i.e. {@link 5927 android.hardware.camera2.params.StreamConfigurationMap#isOutputSupportedFor(Class)} 5928 * {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} 5929 5930 For full guarantees, query {@link 5931 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration} with a 5932 processed format -- it will return 0 for a non-stalling stream. 5933 5934 LEGACY devices will support at least 2 processing/non-stalling streams. 5935 </details> 5936 </entry> 5937 <entry name="maxNumOutputProcStalling" type="int32" visibility="java_public" synthetic="true" 5938 hwlevel="legacy"> 5939 <description>The maximum numbers of different types of output streams 5940 that can be configured and used simultaneously by a camera device 5941 for any processed (and stalling) formats. 5942 </description> 5943 <range> 5944 &gt;= 1 5945 </range> 5946 <details> 5947 This value contains the max number of output simultaneous 5948 streams for any processed (but not-stalling) formats. 5949 5950 This lists the upper bound of the number of output streams supported by 5951 the camera device. Using more streams simultaneously may require more hardware and 5952 CPU resources that will consume more power. The image format for this kind of an output stream can 5953 be any non-`RAW` and supported format provided by android.scaler.streamConfigurationMap. 5954 5955 A processed and stalling format is defined as any non-RAW format with a stallDurations 5956 &gt; 0. Typically only the {@link 5957 android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG format} is a stalling format. 5958 5959 For full guarantees, query {@link 5960 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration} with a 5961 processed format -- it will return a non-0 value for a stalling stream. 5962 5963 LEGACY devices will support up to 1 processing/stalling stream. 5964 </details> 5965 </entry> 5966 <entry name="maxNumReprocessStreams" type="int32" visibility="system" 5967 deprecated="true" container="array"> 5968 <array> 5969 <size>1</size> 5970 </array> 5971 <description>How many reprocessing streams of any type 5972 can be allocated at the same time.</description> 5973 <deprecation_description> 5974 Not used in HALv3 or newer 5975 </deprecation_description> 5976 <range>&gt;= 0</range> 5977 <details> 5978 Only used by HAL2.x. 5979 5980 When set to 0, it means no reprocess stream is supported. 5981 </details> 5982 <tag id="HAL2" /> 5983 </entry> 5984 <entry name="maxNumInputStreams" type="int32" visibility="java_public" hwlevel="full"> 5985 <description> 5986 The maximum numbers of any type of input streams 5987 that can be configured and used simultaneously by a camera device. 5988 </description> 5989 <range> 5990 0 or 1. 5991 </range> 5992 <details>When set to 0, it means no input stream is supported. 5993 5994 The image format for a input stream can be any supported format returned by {@link 5995 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. When using an 5996 input stream, there must be at least one output stream configured to to receive the 5997 reprocessed images. 5998 5999 When an input stream and some output streams are used in a reprocessing request, 6000 only the input buffer will be used to produce these output stream buffers, and a 6001 new sensor image will not be captured. 6002 6003 For example, for Zero Shutter Lag (ZSL) still capture use case, the input 6004 stream image format will be PRIVATE, the associated output stream image format 6005 should be JPEG. 6006 </details> 6007 <hal_details> 6008 For the reprocessing flow and controls, see 6009 hardware/libhardware/include/hardware/camera3.h Section 10 for more details. 6010 </hal_details> 6011 <tag id="REPROC" /> 6012 </entry> 6013 </static> 6014 <dynamic> 6015 <entry name="frameCount" type="int32" visibility="hidden" deprecated="true"> 6016 <description>A frame counter set by the framework. This value monotonically 6017 increases with every new result (that is, each new result has a unique 6018 frameCount value).</description> 6019 <deprecation_description> 6020 Not used in HALv3 or newer 6021 </deprecation_description> 6022 <units>count of frames</units> 6023 <range>&gt; 0</range> 6024 <details>Reset on release()</details> 6025 </entry> 6026 <clone entry="android.request.id" kind="controls"></clone> 6027 <clone entry="android.request.metadataMode" 6028 kind="controls"></clone> 6029 <clone entry="android.request.outputStreams" 6030 kind="controls"></clone> 6031 <entry name="pipelineDepth" type="byte" visibility="public" hwlevel="legacy"> 6032 <description>Specifies the number of pipeline stages the frame went 6033 through from when it was exposed to when the final completed result 6034 was available to the framework.</description> 6035 <range>&lt;= android.request.pipelineMaxDepth</range> 6036 <details>Depending on what settings are used in the request, and 6037 what streams are configured, the data may undergo less processing, 6038 and some pipeline stages skipped. 6039 6040 See android.request.pipelineMaxDepth for more details. 6041 </details> 6042 <hal_details> 6043 This value must always represent the accurate count of how many 6044 pipeline stages were actually used. 6045 </hal_details> 6046 </entry> 6047 </dynamic> 6048 <static> 6049 <entry name="pipelineMaxDepth" type="byte" visibility="public" hwlevel="legacy"> 6050 <description>Specifies the number of maximum pipeline stages a frame 6051 has to go through from when it's exposed to when it's available 6052 to the framework.</description> 6053 <details>A typical minimum value for this is 2 (one stage to expose, 6054 one stage to readout) from the sensor. The ISP then usually adds 6055 its own stages to do custom HW processing. Further stages may be 6056 added by SW processing. 6057 6058 Depending on what settings are used (e.g. YUV, JPEG) and what 6059 processing is enabled (e.g. face detection), the actual pipeline 6060 depth (specified by android.request.pipelineDepth) may be less than 6061 the max pipeline depth. 6062 6063 A pipeline depth of X stages is equivalent to a pipeline latency of 6064 X frame intervals. 6065 6066 This value will normally be 8 or less, however, for high speed capture session, 6067 the max pipeline depth will be up to 8 x size of high speed capture request list. 6068 </details> 6069 <hal_details> 6070 This value should be 4 or less, expect for the high speed recording session, where the 6071 max batch sizes may be larger than 1. 6072 </hal_details> 6073 </entry> 6074 <entry name="partialResultCount" type="int32" visibility="public" optional="true"> 6075 <description>Defines how many sub-components 6076 a result will be composed of. 6077 </description> 6078 <range>&gt;= 1</range> 6079 <details>In order to combat the pipeline latency, partial results 6080 may be delivered to the application layer from the camera device as 6081 soon as they are available. 6082 6083 Optional; defaults to 1. A value of 1 means that partial 6084 results are not supported, and only the final TotalCaptureResult will 6085 be produced by the camera device. 6086 6087 A typical use case for this might be: after requesting an 6088 auto-focus (AF) lock the new AF state might be available 50% 6089 of the way through the pipeline. The camera device could 6090 then immediately dispatch this state via a partial result to 6091 the application, and the rest of the metadata via later 6092 partial results. 6093 </details> 6094 </entry> 6095 <entry name="availableCapabilities" type="byte" visibility="public" 6096 enum="true" container="array" hwlevel="legacy"> 6097 <array> 6098 <size>n</size> 6099 </array> 6100 <enum> 6101 <value>BACKWARD_COMPATIBLE 6102 <notes>The minimal set of capabilities that every camera 6103 device (regardless of android.info.supportedHardwareLevel) 6104 supports. 6105 6106 This capability is listed by all normal devices, and 6107 indicates that the camera device has a feature set 6108 that's comparable to the baseline requirements for the 6109 older android.hardware.Camera API. 6110 6111 Devices with the DEPTH_OUTPUT capability might not list this 6112 capability, indicating that they support only depth measurement, 6113 not standard color output. 6114 </notes> 6115 </value> 6116 <value optional="true">MANUAL_SENSOR 6117 <notes> 6118 The camera device can be manually controlled (3A algorithms such 6119 as auto-exposure, and auto-focus can be bypassed). 6120 The camera device supports basic manual control of the sensor image 6121 acquisition related stages. This means the following controls are 6122 guaranteed to be supported: 6123 6124 * Manual frame duration control 6125 * android.sensor.frameDuration 6126 * android.sensor.info.maxFrameDuration 6127 * Manual exposure control 6128 * android.sensor.exposureTime 6129 * android.sensor.info.exposureTimeRange 6130 * Manual sensitivity control 6131 * android.sensor.sensitivity 6132 * android.sensor.info.sensitivityRange 6133 * Manual lens control (if the lens is adjustable) 6134 * android.lens.* 6135 * Manual flash control (if a flash unit is present) 6136 * android.flash.* 6137 * Manual black level locking 6138 * android.blackLevel.lock 6139 * Auto exposure lock 6140 * android.control.aeLock 6141 6142 If any of the above 3A algorithms are enabled, then the camera 6143 device will accurately report the values applied by 3A in the 6144 result. 6145 6146 A given camera device may also support additional manual sensor controls, 6147 but this capability only covers the above list of controls. 6148 6149 If this is supported, android.scaler.streamConfigurationMap will 6150 additionally return a min frame duration that is greater than 6151 zero for each supported size-format combination. 6152 6153 For camera devices with LOGICAL_MULTI_CAMERA capability, when the underlying active 6154 physical camera switches, exposureTime, sensitivity, and lens properties may change 6155 even if AE/AF is locked. However, the overall auto exposure and auto focus experience 6156 for users will be consistent. Refer to LOGICAL_MULTI_CAMERA capability for details. 6157 </notes> 6158 </value> 6159 <value optional="true">MANUAL_POST_PROCESSING 6160 <notes> 6161 The camera device post-processing stages can be manually controlled. 6162 The camera device supports basic manual control of the image post-processing 6163 stages. This means the following controls are guaranteed to be supported: 6164 6165 * Manual tonemap control 6166 * android.tonemap.curve 6167 * android.tonemap.mode 6168 * android.tonemap.maxCurvePoints 6169 * android.tonemap.gamma 6170 * android.tonemap.presetCurve 6171 6172 * Manual white balance control 6173 * android.colorCorrection.transform 6174 * android.colorCorrection.gains 6175 * Manual lens shading map control 6176 * android.shading.mode 6177 * android.statistics.lensShadingMapMode 6178 * android.statistics.lensShadingMap 6179 * android.lens.info.shadingMapSize 6180 * Manual aberration correction control (if aberration correction is supported) 6181 * android.colorCorrection.aberrationMode 6182 * android.colorCorrection.availableAberrationModes 6183 * Auto white balance lock 6184 * android.control.awbLock 6185 6186 If auto white balance is enabled, then the camera device 6187 will accurately report the values applied by AWB in the result. 6188 6189 A given camera device may also support additional post-processing 6190 controls, but this capability only covers the above list of controls. 6191 6192 For camera devices with LOGICAL_MULTI_CAMERA capability, when underlying active 6193 physical camera switches, tonemap, white balance, and shading map may change even if 6194 awb is locked. However, the overall post-processing experience for users will be 6195 consistent. Refer to LOGICAL_MULTI_CAMERA capability for details. 6196 </notes> 6197 </value> 6198 <value optional="true">RAW 6199 <notes> 6200 The camera device supports outputting RAW buffers and 6201 metadata for interpreting them. 6202 6203 Devices supporting the RAW capability allow both for 6204 saving DNG files, and for direct application processing of 6205 raw sensor images. 6206 6207 * RAW_SENSOR is supported as an output format. 6208 * The maximum available resolution for RAW_SENSOR streams 6209 will match either the value in 6210 android.sensor.info.pixelArraySize or 6211 android.sensor.info.preCorrectionActiveArraySize. 6212 * All DNG-related optional metadata entries are provided 6213 by the camera device. 6214 </notes> 6215 </value> 6216 <value optional="true" visibility="java_public">PRIVATE_REPROCESSING 6217 <notes> 6218 The camera device supports the Zero Shutter Lag reprocessing use case. 6219 6220 * One input stream is supported, that is, `android.request.maxNumInputStreams == 1`. 6221 * {@link android.graphics.ImageFormat#PRIVATE} is supported as an output/input format, 6222 that is, {@link android.graphics.ImageFormat#PRIVATE} is included in the lists of 6223 formats returned by {@link 6224 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats} and {@link 6225 android.hardware.camera2.params.StreamConfigurationMap#getOutputFormats}. 6226 * {@link android.hardware.camera2.params.StreamConfigurationMap#getValidOutputFormatsForInput} 6227 returns non-empty int[] for each supported input format returned by {@link 6228 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. 6229 * Each size returned by {@link 6230 android.hardware.camera2.params.StreamConfigurationMap#getInputSizes 6231 getInputSizes(ImageFormat.PRIVATE)} is also included in {@link 6232 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes 6233 getOutputSizes(ImageFormat.PRIVATE)} 6234 * Using {@link android.graphics.ImageFormat#PRIVATE} does not cause a frame rate drop 6235 relative to the sensor's maximum capture rate (at that resolution). 6236 * {@link android.graphics.ImageFormat#PRIVATE} will be reprocessable into both 6237 {@link android.graphics.ImageFormat#YUV_420_888} and 6238 {@link android.graphics.ImageFormat#JPEG} formats. 6239 * For a MONOCHROME camera supporting Y8 format, {@link 6240 android.graphics.ImageFormat#PRIVATE} will be reprocessable into 6241 {@link android.graphics.ImageFormat#Y8}. 6242 * The maximum available resolution for PRIVATE streams 6243 (both input/output) will match the maximum available 6244 resolution of JPEG streams. 6245 * Static metadata android.reprocess.maxCaptureStall. 6246 * Only below controls are effective for reprocessing requests and 6247 will be present in capture results, other controls in reprocess 6248 requests will be ignored by the camera device. 6249 * android.jpeg.* 6250 * android.noiseReduction.mode 6251 * android.edge.mode 6252 * android.noiseReduction.availableNoiseReductionModes and 6253 android.edge.availableEdgeModes will both list ZERO_SHUTTER_LAG as a supported mode. 6254 </notes> 6255 </value> 6256 <value optional="true">READ_SENSOR_SETTINGS 6257 <notes> 6258 The camera device supports accurately reporting the sensor settings for many of 6259 the sensor controls while the built-in 3A algorithm is running. This allows 6260 reporting of sensor settings even when these settings cannot be manually changed. 6261 6262 The values reported for the following controls are guaranteed to be available 6263 in the CaptureResult, including when 3A is enabled: 6264 6265 * Exposure control 6266 * android.sensor.exposureTime 6267 * Sensitivity control 6268 * android.sensor.sensitivity 6269 * Lens controls (if the lens is adjustable) 6270 * android.lens.focusDistance 6271 * android.lens.aperture 6272 6273 This capability is a subset of the MANUAL_SENSOR control capability, and will 6274 always be included if the MANUAL_SENSOR capability is available. 6275 </notes> 6276 </value> 6277 <value optional="true">BURST_CAPTURE 6278 <notes> 6279 The camera device supports capturing high-resolution images at >= 20 frames per 6280 second, in at least the uncompressed YUV format, when post-processing settings are 6281 set to FAST. Additionally, all image resolutions less than 24 megapixels can be 6282 captured at >= 10 frames per second. Here, 'high resolution' means at least 8 6283 megapixels, or the maximum resolution of the device, whichever is smaller. 6284 </notes> 6285 <sdk_notes> 6286 More specifically, this means that a size matching the camera device's active array 6287 size is listed as a supported size for the {@link 6288 android.graphics.ImageFormat#YUV_420_888} format in either {@link 6289 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} or {@link 6290 android.hardware.camera2.params.StreamConfigurationMap#getHighResolutionOutputSizes}, 6291 with a minimum frame duration for that format and size of either <= 1/20 s, or 6292 <= 1/10 s if the image size is less than 24 megapixels, respectively; and 6293 the android.control.aeAvailableTargetFpsRanges entry lists at least one FPS range 6294 where the minimum FPS is >= 1 / minimumFrameDuration for the maximum-size 6295 YUV_420_888 format. If that maximum size is listed in {@link 6296 android.hardware.camera2.params.StreamConfigurationMap#getHighResolutionOutputSizes}, 6297 then the list of resolutions for YUV_420_888 from {@link 6298 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} contains at 6299 least one resolution >= 8 megapixels, with a minimum frame duration of <= 1/20 6300 s. 6301 6302 If the device supports the {@link 6303 android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10}, {@link 6304 android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12}, {@link 6305 android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8}, then those can also be 6306 captured at the same rate as the maximum-size YUV_420_888 resolution is. 6307 6308 If the device supports the PRIVATE_REPROCESSING capability, then the same guarantees 6309 as for the YUV_420_888 format also apply to the {@link 6310 android.graphics.ImageFormat#PRIVATE} format. 6311 6312 In addition, the android.sync.maxLatency field is guaranteed to have a value between 0 6313 and 4, inclusive. android.control.aeLockAvailable and android.control.awbLockAvailable 6314 are also guaranteed to be `true` so burst capture with these two locks ON yields 6315 consistent image output. 6316 </sdk_notes> 6317 <ndk_notes> 6318 More specifically, this means that at least one output {@link 6319 android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888} size listed in 6320 {@link 6321 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 6322 is larger or equal to the 'high resolution' defined above, and can be captured at at 6323 least 20 fps. For the largest {@link 6324 android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888} size listed in 6325 {@link 6326 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}, 6327 camera device can capture this size for at least 10 frames per second if the size is 6328 less than 24 megapixels. Also the android.control.aeAvailableTargetFpsRanges entry 6329 lists at least one FPS range where the minimum FPS is >= 1 / minimumFrameDuration 6330 for the largest YUV_420_888 size. 6331 6332 If the device supports the {@link 6333 android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10}, {@link 6334 android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12}, {@link 6335 android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8}, then those can also be 6336 captured at the same rate as the maximum-size YUV_420_888 resolution is. 6337 6338 In addition, the android.sync.maxLatency field is guaranteed to have a value between 0 6339 and 4, inclusive. android.control.aeLockAvailable and android.control.awbLockAvailable 6340 are also guaranteed to be `true` so burst capture with these two locks ON yields 6341 consistent image output. 6342 </ndk_notes> 6343 </value> 6344 <value optional="true" visibility="java_public">YUV_REPROCESSING 6345 <notes> 6346 The camera device supports the YUV_420_888 reprocessing use case, similar as 6347 PRIVATE_REPROCESSING, This capability requires the camera device to support the 6348 following: 6349 6350 * One input stream is supported, that is, `android.request.maxNumInputStreams == 1`. 6351 * {@link android.graphics.ImageFormat#YUV_420_888} is supported as an output/input 6352 format, that is, YUV_420_888 is included in the lists of formats returned by {@link 6353 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats} and {@link 6354 android.hardware.camera2.params.StreamConfigurationMap#getOutputFormats}. 6355 * {@link 6356 android.hardware.camera2.params.StreamConfigurationMap#getValidOutputFormatsForInput} 6357 returns non-empty int[] for each supported input format returned by {@link 6358 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. 6359 * Each size returned by {@link 6360 android.hardware.camera2.params.StreamConfigurationMap#getInputSizes 6361 getInputSizes(YUV_420_888)} is also included in {@link 6362 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes 6363 getOutputSizes(YUV_420_888)} 6364 * Using {@link android.graphics.ImageFormat#YUV_420_888} does not cause a frame rate 6365 drop relative to the sensor's maximum capture rate (at that resolution). 6366 * {@link android.graphics.ImageFormat#YUV_420_888} will be reprocessable into both 6367 {@link android.graphics.ImageFormat#YUV_420_888} and {@link 6368 android.graphics.ImageFormat#JPEG} formats. 6369 * The maximum available resolution for {@link 6370 android.graphics.ImageFormat#YUV_420_888} streams (both input/output) will match the 6371 maximum available resolution of {@link android.graphics.ImageFormat#JPEG} streams. 6372 * For a MONOCHROME camera with Y8 format support, all the requirements mentioned 6373 above for YUV_420_888 apply for Y8 format as well. 6374 * Static metadata android.reprocess.maxCaptureStall. 6375 * Only the below controls are effective for reprocessing requests and will be present 6376 in capture results. The reprocess requests are from the original capture results 6377 that are associated with the intermediate {@link 6378 android.graphics.ImageFormat#YUV_420_888} output buffers. All other controls in the 6379 reprocess requests will be ignored by the camera device. 6380 * android.jpeg.* 6381 * android.noiseReduction.mode 6382 * android.edge.mode 6383 * android.reprocess.effectiveExposureFactor 6384 * android.noiseReduction.availableNoiseReductionModes and 6385 android.edge.availableEdgeModes will both list ZERO_SHUTTER_LAG as a supported mode. 6386 </notes> 6387 </value> 6388 <value optional="true">DEPTH_OUTPUT 6389 <notes> 6390 The camera device can produce depth measurements from its field of view. 6391 6392 This capability requires the camera device to support the following: 6393 6394 * {@link android.graphics.ImageFormat#DEPTH16|AIMAGE_FORMAT_DEPTH16} is supported as 6395 an output format. 6396 * {@link 6397 android.graphics.ImageFormat#DEPTH_POINT_CLOUD|AIMAGE_FORMAT_DEPTH_POINT_CLOUD} is 6398 optionally supported as an output format. 6399 * This camera device, and all camera devices with the same android.lens.facing, will 6400 list the following calibration metadata entries in both {@link 6401 android.hardware.camera2.CameraCharacteristics|ACameraManager_getCameraCharacteristics} 6402 and {@link 6403 android.hardware.camera2.CaptureResult|ACameraCaptureSession_captureCallback_result}: 6404 - android.lens.poseTranslation 6405 - android.lens.poseRotation 6406 - android.lens.intrinsicCalibration 6407 - android.lens.distortion 6408 * The android.depth.depthIsExclusive entry is listed by this device. 6409 * As of Android P, the android.lens.poseReference entry is listed by this device. 6410 * A LIMITED camera with only the DEPTH_OUTPUT capability does not have to support 6411 normal YUV_420_888, Y8, JPEG, and PRIV-format outputs. It only has to support the 6412 DEPTH16 format. 6413 6414 Generally, depth output operates at a slower frame rate than standard color capture, 6415 so the DEPTH16 and DEPTH_POINT_CLOUD formats will commonly have a stall duration that 6416 should be accounted for (see {@link 6417 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration|ACAMERA_DEPTH_AVAILABLE_DEPTH_STALL_DURATIONS}). 6418 On a device that supports both depth and color-based output, to enable smooth preview, 6419 using a repeating burst is recommended, where a depth-output target is only included 6420 once every N frames, where N is the ratio between preview output rate and depth output 6421 rate, including depth stall time. 6422 </notes> 6423 </value> 6424 <value optional="true" visibility="java_public">CONSTRAINED_HIGH_SPEED_VIDEO 6425 <notes> 6426 The device supports constrained high speed video recording (frame rate >=120fps) use 6427 case. The camera device will support high speed capture session created by {@link 6428 android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}, which 6429 only accepts high speed request lists created by {@link 6430 android.hardware.camera2.CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList}. 6431 6432 A camera device can still support high speed video streaming by advertising the high 6433 speed FPS ranges in android.control.aeAvailableTargetFpsRanges. For this case, all 6434 normal capture request per frame control and synchronization requirements will apply 6435 to the high speed fps ranges, the same as all other fps ranges. This capability 6436 describes the capability of a specialized operating mode with many limitations (see 6437 below), which is only targeted at high speed video recording. 6438 6439 The supported high speed video sizes and fps ranges are specified in {@link 6440 android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoFpsRanges}. 6441 To get desired output frame rates, the application is only allowed to select video 6442 size and FPS range combinations provided by {@link 6443 android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoSizes}. The 6444 fps range can be controlled via android.control.aeTargetFpsRange. 6445 6446 In this capability, the camera device will override aeMode, awbMode, and afMode to 6447 ON, AUTO, and CONTINUOUS_VIDEO, respectively. All post-processing block mode 6448 controls will be overridden to be FAST. Therefore, no manual control of capture 6449 and post-processing parameters is possible. All other controls operate the 6450 same as when android.control.mode == AUTO. This means that all other 6451 android.control.* fields continue to work, such as 6452 6453 * android.control.aeTargetFpsRange 6454 * android.control.aeExposureCompensation 6455 * android.control.aeLock 6456 * android.control.awbLock 6457 * android.control.effectMode 6458 * android.control.aeRegions 6459 * android.control.afRegions 6460 * android.control.awbRegions 6461 * android.control.afTrigger 6462 * android.control.aePrecaptureTrigger 6463 * android.control.zoomRatio 6464 6465 Outside of android.control.*, the following controls will work: 6466 6467 * android.flash.mode (TORCH mode only, automatic flash for still capture will not 6468 work since aeMode is ON) 6469 * android.lens.opticalStabilizationMode (if it is supported) 6470 * android.scaler.cropRegion 6471 * android.statistics.faceDetectMode (if it is supported) 6472 6473 For high speed recording use case, the actual maximum supported frame rate may 6474 be lower than what camera can output, depending on the destination Surfaces for 6475 the image data. For example, if the destination surface is from video encoder, 6476 the application need check if the video encoder is capable of supporting the 6477 high frame rate for a given video size, or it will end up with lower recording 6478 frame rate. If the destination surface is from preview window, the actual preview frame 6479 rate will be bounded by the screen refresh rate. 6480 6481 The camera device will only support up to 2 high speed simultaneous output surfaces 6482 (preview and recording surfaces) in this mode. Above controls will be effective only 6483 if all of below conditions are true: 6484 6485 * The application creates a camera capture session with no more than 2 surfaces via 6486 {@link 6487 android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}. The 6488 targeted surfaces must be preview surface (either from {@link 6489 android.view.SurfaceView} or {@link android.graphics.SurfaceTexture}) or recording 6490 surface(either from {@link android.media.MediaRecorder#getSurface} or {@link 6491 android.media.MediaCodec#createInputSurface}). 6492 * The stream sizes are selected from the sizes reported by 6493 {@link android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoSizes}. 6494 * The FPS ranges are selected from {@link 6495 android.hardware.camera2.params.StreamConfigurationMap#getHighSpeedVideoFpsRanges}. 6496 6497 When above conditions are NOT satisfied, 6498 {@link android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession} 6499 will fail. 6500 6501 Switching to a FPS range that has different maximum FPS may trigger some camera device 6502 reconfigurations, which may introduce extra latency. It is recommended that 6503 the application avoids unnecessary maximum target FPS changes as much as possible 6504 during high speed streaming. 6505 </notes> 6506 </value> 6507 <value optional="true" hal_version="3.3" >MOTION_TRACKING 6508 <notes> 6509 The camera device supports the MOTION_TRACKING value for 6510 android.control.captureIntent, which limits maximum exposure time to 20 ms. 6511 6512 This limits the motion blur of capture images, resulting in better image tracking 6513 results for use cases such as image stabilization or augmented reality. 6514 </notes> 6515 </value> 6516 <value optional="true" hal_version="3.3">LOGICAL_MULTI_CAMERA 6517 <notes> 6518 The camera device is a logical camera backed by two or more physical cameras. 6519 6520 In API level 28, the physical cameras must also be exposed to the application via 6521 {@link android.hardware.camera2.CameraManager#getCameraIdList}. 6522 6523 Starting from API level 29: 6524 6525 * Some or all physical cameras may not be independently exposed to the application, 6526 in which case the physical camera IDs will not be available in 6527 {@link android.hardware.camera2.CameraManager#getCameraIdList}. But the 6528 application can still query the physical cameras' characteristics by calling 6529 {@link android.hardware.camera2.CameraManager#getCameraCharacteristics}. 6530 * If a physical camera is hidden from camera ID list, the mandatory stream 6531 combinations for that physical camera must be supported through the logical camera 6532 using physical streams. One exception is that in API level 30, a physical camera 6533 may become unavailable via 6534 {@link CameraManager.AvailabilityCallback#onPhysicalCameraUnavailable|ACameraManager_PhysicalCameraAvailabilityCallback} 6535 callback. 6536 6537 Combinations of logical and physical streams, or physical streams from different 6538 physical cameras are not guaranteed. However, if the camera device supports 6539 {@link CameraDevice#isSessionConfigurationSupported|ACameraDevice_isSessionConfigurationSupported}, 6540 application must be able to query whether a stream combination involving physical 6541 streams is supported by calling 6542 {@link CameraDevice#isSessionConfigurationSupported|ACameraDevice_isSessionConfigurationSupported}. 6543 6544 Camera application shouldn't assume that there are at most 1 rear camera and 1 front 6545 camera in the system. For an application that switches between front and back cameras, 6546 the recommendation is to switch between the first rear camera and the first front 6547 camera in the list of supported camera devices. 6548 6549 This capability requires the camera device to support the following: 6550 6551 * The IDs of underlying physical cameras are returned via 6552 {@link android.hardware.camera2.CameraCharacteristics#getPhysicalCameraIds}. 6553 * This camera device must list static metadata 6554 android.logicalMultiCamera.sensorSyncType in 6555 {@link android.hardware.camera2.CameraCharacteristics}. 6556 * The underlying physical cameras' static metadata must list the following entries, 6557 so that the application can correlate pixels from the physical streams: 6558 - android.lens.poseReference 6559 - android.lens.poseRotation 6560 - android.lens.poseTranslation 6561 - android.lens.intrinsicCalibration 6562 - android.lens.distortion 6563 * The SENSOR_INFO_TIMESTAMP_SOURCE of the logical device and physical devices must be 6564 the same. 6565 * The logical camera must be LIMITED or higher device. 6566 6567 A logical camera device's dynamic metadata may contain 6568 android.logicalMultiCamera.activePhysicalId to notify the application of the current 6569 active physical camera Id. An active physical camera is the physical camera from which 6570 the logical camera's main image data outputs (YUV or RAW) and metadata come from. 6571 In addition, this serves as an indication which physical camera is used to output to 6572 a RAW stream, or in case only physical cameras support RAW, which physical RAW stream 6573 the application should request. 6574 6575 Logical camera's static metadata tags below describe the default active physical 6576 camera. An active physical camera is default if it's used when application directly 6577 uses requests built from a template. All templates will default to the same active 6578 physical camera. 6579 6580 - android.sensor.info.sensitivityRange 6581 - android.sensor.info.colorFilterArrangement 6582 - android.sensor.info.exposureTimeRange 6583 - android.sensor.info.maxFrameDuration 6584 - android.sensor.info.physicalSize 6585 - android.sensor.info.whiteLevel 6586 - android.sensor.info.lensShadingApplied 6587 - android.sensor.referenceIlluminant1 6588 - android.sensor.referenceIlluminant2 6589 - android.sensor.calibrationTransform1 6590 - android.sensor.calibrationTransform2 6591 - android.sensor.colorTransform1 6592 - android.sensor.colorTransform2 6593 - android.sensor.forwardMatrix1 6594 - android.sensor.forwardMatrix2 6595 - android.sensor.blackLevelPattern 6596 - android.sensor.maxAnalogSensitivity 6597 - android.sensor.opticalBlackRegions 6598 - android.sensor.availableTestPatternModes 6599 - android.lens.info.hyperfocalDistance 6600 - android.lens.info.minimumFocusDistance 6601 - android.lens.info.focusDistanceCalibration 6602 - android.lens.poseRotation 6603 - android.lens.poseTranslation 6604 - android.lens.intrinsicCalibration 6605 - android.lens.poseReference 6606 - android.lens.distortion 6607 6608 The field of view of non-RAW physical streams must not be smaller than that of the 6609 non-RAW logical streams, or the maximum field-of-view of the physical camera, 6610 whichever is smaller. The application should check the physical capture result 6611 metadata for how the physical streams are cropped or zoomed. More specifically, given 6612 the physical camera result metadata, the effective horizontal field-of-view of the 6613 physical camera is: 6614 6615 fov = 2 * atan2(cropW * sensorW / (2 * zoomRatio * activeArrayW), focalLength) 6616 6617 where the equation parameters are the physical camera's crop region width, physical 6618 sensor width, zoom ratio, active array width, and focal length respectively. Typically 6619 the physical stream of active physical camera has the same field-of-view as the 6620 logical streams. However, the same may not be true for physical streams from 6621 non-active physical cameras. For example, if the logical camera has a wide-ultrawide 6622 configuration where the wide lens is the default, when the crop region is set to the 6623 logical camera's active array size, (and the zoom ratio set to 1.0 starting from 6624 Android 11), a physical stream for the ultrawide camera may prefer outputting images 6625 with larger field-of-view than that of the wide camera for better stereo matching 6626 margin or more robust motion tracking. At the same time, the physical non-RAW streams' 6627 field of view must not be smaller than the requested crop region and zoom ratio, as 6628 long as it's within the physical lens' capability. For example, for a logical camera 6629 with wide-tele lens configuration where the wide lens is the default, if the logical 6630 camera's crop region is set to maximum size, and zoom ratio set to 1.0, the physical 6631 stream for the tele lens will be configured to its maximum size crop region (no zoom). 6632 6633 *Deprecated:* Prior to Android 11, the field of view of all non-RAW physical streams 6634 cannot be larger than that of non-RAW logical streams. If the logical camera has a 6635 wide-ultrawide lens configuration where the wide lens is the default, when the logical 6636 camera's crop region is set to maximum size, the FOV of the physical streams for the 6637 ultrawide lens will be the same as the logical stream, by making the crop region 6638 smaller than its active array size to compensate for the smaller focal length. 6639 6640 For a logical camera, typically the underlying physical cameras have different RAW 6641 capabilities (such as resolution or CFA pattern). There are two ways for the 6642 application to capture RAW images from the logical camera: 6643 6644 * If the logical camera has RAW capability, the application can create and use RAW 6645 streams in the same way as before. In case a RAW stream is configured, to maintain 6646 backward compatibility, the camera device makes sure the default active physical 6647 camera remains active and does not switch to other physical cameras. (One exception 6648 is that, if the logical camera consists of identical image sensors and advertises 6649 multiple focalLength due to different lenses, the camera device may generate RAW 6650 images from different physical cameras based on the focalLength being set by the 6651 application.) This backward-compatible approach usually results in loss of optical 6652 zoom, to telephoto lens or to ultrawide lens. 6653 * Alternatively, if supported by the device, 6654 {@link android.hardware.camera2.MultiResolutionImageReader} 6655 can be used to capture RAW images from one of the underlying physical cameras ( 6656 depending on current zoom level). Because different physical cameras may have 6657 different RAW characteristics, the application needs to use the characteristics 6658 and result metadata of the active physical camera for the relevant RAW metadata. 6659 6660 The capture request and result metadata tags required for backward compatible camera 6661 functionalities will be solely based on the logical camera capability. On the other 6662 hand, the use of manual capture controls (sensor or post-processing) with a 6663 logical camera may result in unexpected behavior when the HAL decides to switch 6664 between physical cameras with different characteristics under the hood. For example, 6665 when the application manually sets exposure time and sensitivity while zooming in, 6666 the brightness of the camera images may suddenly change because HAL switches from one 6667 physical camera to the other. 6668 </notes> 6669 </value> 6670 <value optional="true" hal_version="3.3" >MONOCHROME 6671 <notes> 6672 The camera device is a monochrome camera that doesn't contain a color filter array, 6673 and for YUV_420_888 stream, the pixel values on U and V planes are all 128. 6674 6675 A MONOCHROME camera must support the guaranteed stream combinations required for 6676 its device level and capabilities. Additionally, if the monochrome camera device 6677 supports Y8 format, all mandatory stream combination requirements related to {@link 6678 android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888 YUV_420_888} apply 6679 to {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} as well. There are no 6680 mandatory stream combination requirements with regard to 6681 {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8 Y8} for Bayer camera devices. 6682 6683 Starting from Android Q, the SENSOR_INFO_COLOR_FILTER_ARRANGEMENT of a MONOCHROME 6684 camera will be either MONO or NIR. 6685 </notes> 6686 </value> 6687 <value optional="true" hal_version="3.4" >SECURE_IMAGE_DATA 6688 <notes> 6689 The camera device is capable of writing image data into a region of memory 6690 inaccessible to Android userspace or the Android kernel, and only accessible to 6691 trusted execution environments (TEE). 6692 </notes> 6693 </value> 6694 <value optional="true" hal_version="3.5" >SYSTEM_CAMERA 6695 <notes> 6696 The camera device is only accessible by Android's system components and privileged 6697 applications. Processes need to have the android.permission.SYSTEM_CAMERA in 6698 addition to android.permission.CAMERA in order to connect to this camera device. 6699 </notes> 6700 </value> 6701 <value optional="true" visibility="java_public" hal_version="3.5">OFFLINE_PROCESSING 6702 <notes> 6703 The camera device supports the OFFLINE_PROCESSING use case. 6704 6705 With OFFLINE_PROCESSING capability, the application can switch an ongoing 6706 capture session to offline mode by calling the 6707 CameraCaptureSession#switchToOffline method and specify streams to be kept in offline 6708 mode. The camera will then stop currently active repeating requests, prepare for 6709 some requests to go into offline mode, and return an offline session object. After 6710 the switchToOffline call returns, the original capture session is in closed state as 6711 if the CameraCaptureSession#close method has been called. 6712 In the offline mode, all inflight requests will continue to be processed in the 6713 background, and the application can immediately close the camera or create a new 6714 capture session without losing those requests' output images and capture results. 6715 6716 While the camera device is processing offline requests, it 6717 might not be able to support all stream configurations it can support 6718 without offline requests. When that happens, the createCaptureSession 6719 method call will fail. The following stream configurations are guaranteed to work 6720 without hitting the resource busy exception: 6721 6722 * One ongoing offline session: target one output surface of YUV or 6723 JPEG format, any resolution. 6724 * The active camera capture session: 6725 1. One preview surface (SurfaceView or SurfaceTexture) up to 1920 width 6726 1. One YUV ImageReader surface up to 1920 width 6727 1. One Jpeg ImageReader, any resolution: the camera device is 6728 allowed to slow down JPEG output speed by 50% if there is any ongoing offline 6729 session. 6730 1. If the device supports PRIVATE_REPROCESSING, one pair of ImageWriter/ImageReader 6731 surfaces of private format, with the same resolution that is larger or equal to 6732 the JPEG ImageReader resolution above. 6733 * Alternatively, the active camera session above can be replaced by an legacy 6734 {@link android.hardware.Camera Camera} with the following parameter settings: 6735 1. Preview size up to 1920 width 6736 1. Preview callback size up to 1920 width 6737 1. Video size up to 1920 width 6738 1. Picture size, any resolution: the camera device is 6739 allowed to slow down JPEG output speed by 50% if there is any ongoing offline 6740 session. 6741 </notes> 6742 </value> 6743 <value optional="true" hal_version="3.6" >ULTRA_HIGH_RESOLUTION_SENSOR 6744 <notes> 6745 This camera device is capable of producing ultra high resolution images in 6746 addition to the image sizes described in the 6747 android.scaler.streamConfigurationMap. 6748 It can operate in 'default' mode and 'max resolution' mode. It generally does this 6749 by binning pixels in 'default' mode and not binning them in 'max resolution' mode. 6750 `android.scaler.streamConfigurationMap` describes the streams supported in 'default' 6751 mode. 6752 The stream configurations supported in 'max resolution' mode are described by 6753 `android.scaler.streamConfigurationMapMaximumResolution`. 6754 The maximum resolution mode pixel array size of a camera device 6755 (`android.sensor.info.pixelArraySize`) with this capability, 6756 will be at least 24 megapixels. 6757 </notes> 6758 </value> 6759 <value optional="true" visibility="java_public" hal_version="3.6">REMOSAIC_REPROCESSING 6760 <notes> 6761 The device supports reprocessing from the `RAW_SENSOR` format with a bayer pattern 6762 given by android.sensor.info.binningFactor (m x n group of pixels with the same 6763 color filter) to a remosaiced regular bayer pattern. 6764 6765 This capability will only be present for devices with 6766 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 6767 capability. When 6768 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 6769 devices do not advertise this capability, 6770 {@link android.graphics.ImageFormat#RAW_SENSOR} images will already have a 6771 regular bayer pattern. 6772 6773 If a `RAW_SENSOR` stream is requested along with another non-RAW stream in a 6774 {@link android.hardware.camera2.CaptureRequest} (if multiple streams are supported 6775 when android.sensor.pixelMode is set to 6776 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}), 6777 the `RAW_SENSOR` stream will have a regular bayer pattern. 6778 6779 This capability requires the camera device to support the following : 6780 6781 * The {@link android.hardware.camera2.params.StreamConfigurationMap} mentioned below 6782 refers to the one, described by 6783 `android.scaler.streamConfigurationMapMaximumResolution`. 6784 * One input stream is supported, that is, `android.request.maxNumInputStreams == 1`. 6785 * {@link android.graphics.ImageFormat#RAW_SENSOR} is supported as an output/input 6786 format, that is, {@link android.graphics.ImageFormat#RAW_SENSOR} is included in the 6787 lists of formats returned by {@link 6788 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats} and {@link 6789 android.hardware.camera2.params.StreamConfigurationMap#getOutputFormats}. 6790 * {@link android.hardware.camera2.params.StreamConfigurationMap#getValidOutputFormatsForInput} 6791 returns non-empty int[] for each supported input format returned by {@link 6792 android.hardware.camera2.params.StreamConfigurationMap#getInputFormats}. 6793 * Each size returned by {@link 6794 android.hardware.camera2.params.StreamConfigurationMap#getInputSizes 6795 getInputSizes(ImageFormat.RAW_SENSOR)} is also included in {@link 6796 android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes 6797 getOutputSizes(ImageFormat.RAW_SENSOR)} 6798 * Using {@link android.graphics.ImageFormat#RAW_SENSOR} does not cause a frame rate 6799 drop relative to the sensor's maximum capture rate (at that resolution). 6800 * No CaptureRequest controls will be applicable when a request has an input target 6801 with {@link android.graphics.ImageFormat#RAW_SENSOR} format. 6802 </notes> 6803 </value> 6804 <value optional="true" visibility="java_public" hal_version="3.8">DYNAMIC_RANGE_TEN_BIT 6805 <notes> 6806 The device supports one or more 10-bit camera outputs according to the dynamic range 6807 profiles specified in 6808 {@link android.hardware.camera2.params.DynamicRangeProfiles#getSupportedProfiles}. 6809 They can be configured as part of the capture session initialization via 6810 {@link android.hardware.camera2.params.OutputConfiguration#setDynamicRangeProfile}. 6811 Cameras that enable this capability must also support the following: 6812 6813 * Profile {@link android.hardware.camera2.params.DynamicRangeProfiles#HLG10} 6814 * All mandatory stream combinations for this specific capability as per 6815 [documentation](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#10-bit-output-additional-guaranteed-configurations) 6816 * In case the device is not able to capture some combination of supported 6817 standard 8-bit and/or 10-bit dynamic range profiles within the same capture request, 6818 then those constraints must be listed in 6819 {@link android.hardware.camera2.params.DynamicRangeProfiles#getProfileCaptureRequestConstraints} 6820 * Recommended dynamic range profile listed in 6821 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_RECOMMENDED_TEN_BIT_DYNAMIC_RANGE_PROFILE}. 6822 </notes> 6823 </value> 6824 <value optional="true" hal_version="3.8">STREAM_USE_CASE 6825 <notes> 6826 The camera device supports selecting a per-stream use case via 6827 {@link android.hardware.camera2.params.OutputConfiguration#setStreamUseCase} 6828 so that the device can optimize camera pipeline parameters such as tuning, sensor 6829 mode, or ISP settings for a specific user scenario. 6830 Some sample usages of this capability are: 6831 6832 * Distinguish high quality YUV captures from a regular YUV stream where 6833 the image quality may not be as good as the JPEG stream, or 6834 * Use one stream to serve multiple purposes: viewfinder, video recording and 6835 still capture. This is common with applications that wish to apply edits equally 6836 to preview, saved images, and saved videos. 6837 6838 This capability requires the camera device to support the following 6839 stream use cases: 6840 6841 * DEFAULT for backward compatibility where the application doesn't set 6842 a stream use case 6843 * PREVIEW for live viewfinder and in-app image analysis 6844 * STILL_CAPTURE for still photo capture 6845 * VIDEO_RECORD for recording video clips 6846 * PREVIEW_VIDEO_STILL for one single stream used for viewfinder, video 6847 recording, and still capture. 6848 * VIDEO_CALL for long running video calls 6849 6850 {@link android.hardware.camera2.CameraCharacteristics#SCALER_AVAILABLE_STREAM_USE_CASES} 6851 lists all of the supported stream use cases. 6852 6853 Refer to the 6854 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#stream-use-case-capability-additional-guaranteed-configurations) 6855 for the mandatory stream combinations involving stream use cases, which can also be 6856 queried via {@link android.hardware.camera2.params.MandatoryStreamCombination}. 6857 </notes> 6858 </value> 6859 <value optional="true" visibility="java_public" hal_version="3.9">COLOR_SPACE_PROFILES 6860 <notes> 6861 The device supports querying the possible combinations of color spaces, image 6862 formats, and dynamic range profiles supported by the camera and requesting a 6863 particular color space for a session via 6864 {@link android.hardware.camera2.params.SessionConfiguration#setColorSpace}. 6865 6866 Cameras that enable this capability may or may not also implement dynamic range 6867 profiles. If they don't, 6868 {@link android.hardware.camera2.params.ColorSpaceProfiles#getSupportedDynamicRangeProfiles} 6869 will return only 6870 {@link android.hardware.camera2.params.DynamicRangeProfiles#STANDARD} and 6871 {@link android.hardware.camera2.params.ColorSpaceProfiles#getSupportedColorSpacesForDynamicRange} 6872 will assume support of the 6873 {@link android.hardware.camera2.params.DynamicRangeProfiles#STANDARD} 6874 profile in all combinations of color spaces and image formats. 6875 </notes> 6876 </value> 6877 </enum> 6878 <description>List of capabilities that this camera device 6879 advertises as fully supporting.</description> 6880 <details> 6881 A capability is a contract that the camera device makes in order 6882 to be able to satisfy one or more use cases. 6883 6884 Listing a capability guarantees that the whole set of features 6885 required to support a common use will all be available. 6886 6887 Using a subset of the functionality provided by an unsupported 6888 capability may be possible on a specific camera device implementation; 6889 to do this query each of android.request.availableRequestKeys, 6890 android.request.availableResultKeys, 6891 android.request.availableCharacteristicsKeys. 6892 6893 The following capabilities are guaranteed to be available on 6894 android.info.supportedHardwareLevel `==` FULL devices: 6895 6896 * MANUAL_SENSOR 6897 * MANUAL_POST_PROCESSING 6898 6899 Other capabilities may be available on either FULL or LIMITED 6900 devices, but the application should query this key to be sure. 6901 </details> 6902 <hal_details> 6903 Additional constraint details per-capability will be available 6904 in the Compatibility Test Suite. 6905 6906 Minimum baseline requirements required for the 6907 BACKWARD_COMPATIBLE capability are not explicitly listed. 6908 Instead refer to "BC" tags and the camera CTS tests in the 6909 android.hardware.camera2.cts package. 6910 6911 Listed controls that can be either request or result (e.g. 6912 android.sensor.exposureTime) must be available both in the 6913 request and the result in order to be considered to be 6914 capability-compliant. 6915 6916 For example, if the HAL claims to support MANUAL control, 6917 then exposure time must be configurable via the request _and_ 6918 the actual exposure applied must be available via 6919 the result. 6920 6921 If MANUAL_SENSOR is omitted, the HAL may choose to omit the 6922 android.scaler.availableMinFrameDurations static property entirely. 6923 6924 For PRIVATE_REPROCESSING and YUV_REPROCESSING capabilities, see 6925 hardware/libhardware/include/hardware/camera3.h Section 10 for more information. 6926 6927 Devices that support the MANUAL_SENSOR capability must support the 6928 CAMERA3_TEMPLATE_MANUAL template defined in camera3.h. 6929 6930 Devices that support the PRIVATE_REPROCESSING capability or the 6931 YUV_REPROCESSING capability must support the 6932 CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG template defined in camera3.h. 6933 6934 For DEPTH_OUTPUT, the depth-format keys 6935 android.depth.availableDepthStreamConfigurations, 6936 android.depth.availableDepthMinFrameDurations, 6937 android.depth.availableDepthStallDurations must be available, in 6938 addition to the other keys explicitly mentioned in the DEPTH_OUTPUT 6939 enum notes. The entry android.depth.maxDepthSamples must be available 6940 if the DEPTH_POINT_CLOUD format is supported (HAL pixel format BLOB, dataspace 6941 DEPTH). 6942 6943 For a camera device with LOGICAL_MULTI_CAMERA capability, it should operate in the 6944 same way as a physical camera device based on its hardware level and capabilities. 6945 It's recommended that its feature set is superset of that of individual physical cameras. 6946 6947 * In camera1 API, to maintain application compatibility, for each camera facing, there 6948 may be one or more {logical_camera_id, physical_camera_1_id, physical_camera_2_id, ...} 6949 combinations, where logical_camera_id is composed of physical_camera_N_id, camera 6950 framework will only advertise one camera id 6951 (within the combinations for the particular facing) that is frontmost in the HAL 6952 published camera id list. 6953 For example, if HAL advertises 6 back facing camera IDs (ID0 to ID5), among which ID4 6954 and ID5 are logical cameras backed by ID0+ID1 and ID2+ID3 respectively. In this case, 6955 only ID0 will be available for camera1 API to use. 6956 6957 * Camera HAL is strongly recommended to advertise camera devices with best feature, 6958 power, performance, and latency tradeoffs at the front of the camera id list. 6959 6960 * Camera HAL may switch between physical cameras depending on focalLength, cropRegion, or 6961 zoomRatio. If physical cameras have different sizes, HAL must maintain a single logical 6962 camera activeArraySize/pixelArraySize/preCorrectionActiveArraySize, and must do proper 6963 mapping between logical camera and underlying physical cameras for all related metadata 6964 tags, such as crop region, zoomRatio, 3A regions, and intrinsicCalibration. 6965 6966 * Starting from HIDL ICameraDevice version 3.5, camera HAL must support 6967 isStreamCombinationSupported for application to query whether a particular logical and 6968 physical streams combination are supported. 6969 6970 A MONOCHROME camera device must also advertise BACKWARD_COMPATIBLE capability, and must 6971 not advertise MANUAL_POST_PROCESSING capability. 6972 6973 * To maintain backward compatibility, the camera device must support all 6974 BACKWARD_COMPATIBLE required keys. The android.control.awbAvailableModes key only contains 6975 AUTO, and android.control.awbState are either CONVERGED or LOCKED depending on 6976 android.control.awbLock. 6977 6978 * android.colorCorrection.mode, android.colorCorrection.transform, and 6979 android.colorCorrection.gains must not be in available request and result keys. 6980 As a result, the camera device cannot be a FULL device. However, the HAL can 6981 still advertise other individual capabilities. 6982 6983 * If the device supports tonemap control, only android.tonemap.curveRed is used. 6984 CurveGreen and curveBlue are no-ops. 6985 6986 In Android API level 28, a MONOCHROME camera device must not have RAW capability. From 6987 API level 29, a camera is allowed to have both MONOCHROME and RAW capabilities. 6988 6989 To support the legacy API to ICameraDevice 3.x shim layer, devices advertising 6990 OFFLINE_PROCESSING capability must also support configuring an input stream of the same 6991 size as the picture size if: 6992 6993 * The device supports PRIVATE_REPROCESSING capability 6994 * The device's maximal JPEG resolution can reach 30 FPS min frame duration 6995 * The device does not support HAL based ZSL (android.control.enableZsl) 6996 6997 For devices which support SYSTEM_CAMERA and LOGICAL_MULTI_CAMERA capabilities: 6998 6999 Hidden physical camera ids[1] must not be be shared[2] between public camera devices 7000 and camera devices advertising SYSTEM_CAMERA capability. 7001 7002 [1] - Camera device ids which are advertised in the 7003 ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS list, and not available through 7004 ICameraProvider.getCameraIdList(). 7005 7006 [2] - The ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS lists, must not have common 7007 camera ids. 7008 </hal_details> 7009 </entry> 7010 <entry name="availableRequestKeys" type="int32" visibility="ndk_public" 7011 container="array" hwlevel="legacy"> 7012 <array> 7013 <size>n</size> 7014 </array> 7015 <description>A list of all keys that the camera device has available 7016 to use with {@link android.hardware.camera2.CaptureRequest|ACaptureRequest}.</description> 7017 7018 <details>Attempting to set a key into a CaptureRequest that is not 7019 listed here will result in an invalid request and will be rejected 7020 by the camera device. 7021 7022 This field can be used to query the feature set of a camera device 7023 at a more granular level than capabilities. This is especially 7024 important for optional keys that are not listed under any capability 7025 in android.request.availableCapabilities. 7026 </details> 7027 <hal_details> 7028 Vendor tags can be listed here. Vendor tag metadata should also 7029 use the extensions C api (refer to camera3.h for more details). 7030 7031 Setting/getting vendor tags will be checked against the metadata 7032 vendor extensions API and not against this field. 7033 7034 The HAL must not consume any request tags that are not listed either 7035 here or in the vendor tag list. 7036 7037 The public camera2 API will always make the vendor tags visible 7038 via 7039 {@link android.hardware.camera2.CameraCharacteristics#getAvailableCaptureRequestKeys}. 7040 </hal_details> 7041 </entry> 7042 <entry name="availableResultKeys" type="int32" visibility="ndk_public" 7043 container="array" hwlevel="legacy"> 7044 <array> 7045 <size>n</size> 7046 </array> 7047 <description>A list of all keys that the camera device has available to use with {@link 7048 android.hardware.camera2.CaptureResult|ACameraCaptureSession_captureCallback_result}. 7049 </description> 7050 7051 <details>Attempting to get a key from a CaptureResult that is not 7052 listed here will always return a `null` value. Getting a key from 7053 a CaptureResult that is listed here will generally never return a `null` 7054 value. 7055 7056 The following keys may return `null` unless they are enabled: 7057 7058 * android.statistics.lensShadingMap (non-null iff android.statistics.lensShadingMapMode == ON) 7059 7060 (Those sometimes-null keys will nevertheless be listed here 7061 if they are available.) 7062 7063 This field can be used to query the feature set of a camera device 7064 at a more granular level than capabilities. This is especially 7065 important for optional keys that are not listed under any capability 7066 in android.request.availableCapabilities. 7067 </details> 7068 <hal_details> 7069 Tags listed here must always have an entry in the result metadata, 7070 even if that size is 0 elements. Only array-type tags (e.g. lists, 7071 matrices, strings) are allowed to have 0 elements. 7072 7073 Vendor tags can be listed here. Vendor tag metadata should also 7074 use the extensions C api (refer to camera3.h for more details). 7075 7076 Setting/getting vendor tags will be checked against the metadata 7077 vendor extensions API and not against this field. 7078 7079 The HAL must not produce any result tags that are not listed either 7080 here or in the vendor tag list. 7081 7082 The public camera2 API will always make the vendor tags visible via {@link 7083 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys}. 7084 </hal_details> 7085 </entry> 7086 <entry name="availableCharacteristicsKeys" type="int32" visibility="ndk_public" 7087 container="array" hwlevel="legacy"> 7088 <array> 7089 <size>n</size> 7090 </array> 7091 <description>A list of all keys that the camera device has available to use with {@link 7092 android.hardware.camera2.CameraCharacteristics|ACameraManager_getCameraCharacteristics}. 7093 </description> 7094 <details>This entry follows the same rules as 7095 android.request.availableResultKeys (except that it applies for 7096 CameraCharacteristics instead of CaptureResult). See above for more 7097 details. 7098 </details> 7099 <hal_details> 7100 Keys listed here must always have an entry in the static info metadata, 7101 even if that size is 0 elements. Only array-type tags (e.g. lists, 7102 matrices, strings) are allowed to have 0 elements. 7103 7104 Vendor tags can listed here. Vendor tag metadata should also use 7105 the extensions C api (refer to camera3.h for more details). 7106 7107 Setting/getting vendor tags will be checked against the metadata 7108 vendor extensions API and not against this field. 7109 7110 The HAL must not have any tags in its static info that are not listed 7111 either here or in the vendor tag list. 7112 7113 The public camera2 API will always make the vendor tags visible 7114 via {@link android.hardware.camera2.CameraCharacteristics#getKeys}. 7115 </hal_details> 7116 </entry> 7117 <entry name="availableSessionKeys" type="int32" visibility="ndk_public" 7118 container="array" hwlevel="legacy" hal_version="3.3"> 7119 <array> 7120 <size>n</size> 7121 </array> 7122 <description>A subset of the available request keys that the camera device 7123 can pass as part of the capture session initialization.</description> 7124 7125 <details> This is a subset of android.request.availableRequestKeys which 7126 contains a list of keys that are difficult to apply per-frame and 7127 can result in unexpected delays when modified during the capture session 7128 lifetime. Typical examples include parameters that require a 7129 time-consuming hardware re-configuration or internal camera pipeline 7130 change. For performance reasons we advise clients to pass their initial 7131 values as part of 7132 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 7133 Once the camera capture session is enabled it is also recommended to avoid 7134 changing them from their initial values set in 7135 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 7136 Control over session parameters can still be exerted in capture requests 7137 but clients should be aware and expect delays during their application. 7138 An example usage scenario could look like this: 7139 7140 * The camera client starts by querying the session parameter key list via 7141 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys|ACameraManager_getCameraCharacteristics}. 7142 * Before triggering the capture session create sequence, a capture request 7143 must be built via 7144 {@link CameraDevice#createCaptureRequest|ACameraDevice_createCaptureRequest} 7145 using an appropriate template matching the particular use case. 7146 * The client should go over the list of session parameters and check 7147 whether some of the keys listed matches with the parameters that 7148 they intend to modify as part of the first capture request. 7149 * If there is no such match, the capture request can be passed 7150 unmodified to 7151 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 7152 * If matches do exist, the client should update the respective values 7153 and pass the request to 7154 {@link SessionConfiguration#setSessionParameters|ACameraDevice_createCaptureSessionWithSessionParameters}. 7155 * After the capture session initialization completes the session parameter 7156 key list can continue to serve as reference when posting or updating 7157 further requests. As mentioned above further changes to session 7158 parameters should ideally be avoided, if updates are necessary 7159 however clients could expect a delay/glitch during the 7160 parameter switch. 7161 7162 </details> 7163 <hal_details> 7164 If android.control.aeTargetFpsRange is part of the session parameters and constrained high 7165 speed mode is enabled, then only modifications of the maximum framerate value will be 7166 monitored by the framework and can trigger camera re-configuration. For more information 7167 about framerate ranges during constrained high speed sessions see 7168 {@link android.hardware.camera2.CameraDevice#createConstrainedHighSpeedCaptureSession}. 7169 Vendor tags can be listed here. Vendor tag metadata should also 7170 use the extensions C api (refer to 7171 android.hardware.camera.device.V3_4.StreamConfiguration.sessionParams for more details). 7172 7173 Setting/getting vendor tags will be checked against the metadata 7174 vendor extensions API and not against this field. 7175 7176 The HAL must not consume any request tags in the session parameters that 7177 are not listed either here or in the vendor tag list. 7178 7179 The public camera2 API will always make the vendor tags visible 7180 via 7181 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys}. 7182 </hal_details> 7183 </entry> 7184 <entry name="availablePhysicalCameraRequestKeys" type="int32" visibility="ndk_public" 7185 container="array" hwlevel="limited" hal_version="3.3"> 7186 <array> 7187 <size>n</size> 7188 </array> 7189 <description>A subset of the available request keys that can be overridden for 7190 physical devices backing a logical multi-camera.</description> 7191 <details> 7192 This is a subset of android.request.availableRequestKeys which contains a list 7193 of keys that can be overridden using 7194 {@link android.hardware.camera2.CaptureRequest.Builder#setPhysicalCameraKey}. 7195 The respective value of such request key can be obtained by calling 7196 {@link android.hardware.camera2.CaptureRequest.Builder#getPhysicalCameraKey}. 7197 Capture requests that contain individual physical device requests must be built via 7198 {@link android.hardware.camera2.CameraDevice#createCaptureRequest(int, Set)}. 7199 </details> 7200 <hal_details> 7201 Vendor tags can be listed here. Vendor tag metadata should also 7202 use the extensions C api (refer to 7203 android.hardware.camera.device.V3_4.CaptureRequest.physicalCameraSettings for more 7204 details). 7205 7206 Setting/getting vendor tags will be checked against the metadata 7207 vendor extensions API and not against this field. 7208 7209 The HAL must not consume any request tags in the session parameters that 7210 are not listed either here or in the vendor tag list. 7211 7212 There should be no overlap between this set of keys and the available session keys 7213 {@link android.hardware.camera2.CameraCharacteristics#getAvailableSessionKeys} along 7214 with any other controls that can have impact on the dual-camera sync. 7215 7216 The public camera2 API will always make the vendor tags visible 7217 via 7218 {@link android.hardware.camera2.CameraCharacteristics#getAvailablePhysicalCameraRequestKeys}. 7219 </hal_details> 7220 </entry> 7221 <entry name="characteristicKeysNeedingPermission" type="int32" visibility="hidden" 7222 container="array" hwlevel="legacy" hal_version="3.4"> 7223 <array> 7224 <size>n</size> 7225 </array> 7226 <description>A list of camera characteristics keys that are only available 7227 in case the camera client has camera permission.</description> 7228 7229 <details>The entry contains a subset of 7230 {@link android.hardware.camera2.CameraCharacteristics#getKeys} that require camera clients 7231 to acquire the {@link android.Manifest.permission#CAMERA} permission before calling 7232 {@link android.hardware.camera2.CameraManager#getCameraCharacteristics}. If the 7233 permission is not held by the camera client, then the values of the respective properties 7234 will not be present in {@link android.hardware.camera2.CameraCharacteristics}. 7235 </details> 7236 <hal_details> 7237 Do not set this property directly, camera service will overwrite any previous values. 7238 </hal_details> 7239 </entry> 7240 <entry name="availableDynamicRangeProfiles" type="int32" visibility="java_public" 7241 synthetic="true" optional="true" typedef="dynamicRangeProfiles"> 7242 <description>Devices supporting the 10-bit output capability 7243 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7244 must list their supported dynamic range profiles along with capture request 7245 constraints for specific profile combinations. 7246 </description> 7247 <details> 7248 Camera clients can retrieve the list of supported 10-bit dynamic range profiles by calling 7249 {@link android.hardware.camera2.params.DynamicRangeProfiles#getSupportedProfiles}. 7250 Any of them can be configured by setting OutputConfiguration dynamic range profile in 7251 {@link android.hardware.camera2.params.OutputConfiguration#setDynamicRangeProfile}. 7252 Clients can also check if there are any constraints that limit the combination 7253 of supported profiles that can be referenced within a single capture request by calling 7254 {@link android.hardware.camera2.params.DynamicRangeProfiles#getProfileCaptureRequestConstraints}. 7255 </details> 7256 </entry> 7257 <entry name="availableDynamicRangeProfilesMap" type="int64" visibility="ndk_public" 7258 optional="true" enum="true" container="array" hal_version="3.8"> 7259 <array> 7260 <size>n</size> 7261 <size>3</size> 7262 </array> 7263 <enum> 7264 <value id="0x1">STANDARD 7265 <notes> 7266 8-bit SDR profile which is the default for all non 10-bit output capable devices. 7267 </notes> 7268 </value> 7269 <value id="0x2">HLG10 7270 <notes> 7271 10-bit pixel samples encoded using the Hybrid log-gamma transfer function. 7272 </notes> 7273 </value> 7274 <value id="0x4">HDR10 7275 <notes> 7276 10-bit pixel samples encoded using the SMPTE ST 2084 transfer function. 7277 This profile utilizes internal static metadata to increase the quality 7278 of the capture. 7279 </notes> 7280 </value> 7281 <value id="0x8">HDR10_PLUS 7282 <notes> 7283 10-bit pixel samples encoded using the SMPTE ST 2084 transfer function. 7284 In contrast to HDR10, this profile uses internal per-frame metadata 7285 to further enhance the quality of the capture. 7286 </notes> 7287 </value> 7288 <value id="0x10">DOLBY_VISION_10B_HDR_REF 7289 <notes> 7290 This is a camera mode for Dolby Vision capture optimized for a more scene 7291 accurate capture. This would typically differ from what a specific device 7292 might want to tune for a consumer optimized Dolby Vision general capture. 7293 </notes> 7294 </value> 7295 <value id="0x20">DOLBY_VISION_10B_HDR_REF_PO 7296 <notes> 7297 This is the power optimized mode for 10-bit Dolby Vision HDR Reference Mode. 7298 </notes> 7299 </value> 7300 <value id="0x40">DOLBY_VISION_10B_HDR_OEM 7301 <notes> 7302 This is the camera mode for the default Dolby Vision capture mode for the 7303 specific device. This would be tuned by each specific device for consumer 7304 pleasing results that resonate with their particular audience. We expect 7305 that each specific device would have a different look for their default 7306 Dolby Vision capture. 7307 </notes> 7308 </value> 7309 <value id="0x80">DOLBY_VISION_10B_HDR_OEM_PO 7310 <notes> 7311 This is the power optimized mode for 10-bit Dolby Vision HDR device specific 7312 capture Mode. 7313 </notes> 7314 </value> 7315 <value id="0x100">DOLBY_VISION_8B_HDR_REF 7316 <notes> 7317 This is the 8-bit version of the Dolby Vision reference capture mode optimized 7318 for scene accuracy. 7319 </notes> 7320 </value> 7321 <value id="0x200">DOLBY_VISION_8B_HDR_REF_PO 7322 <notes> 7323 This is the power optimized mode for 8-bit Dolby Vision HDR Reference Mode. 7324 </notes> 7325 </value> 7326 <value id="0x400">DOLBY_VISION_8B_HDR_OEM 7327 <notes> 7328 This is the 8-bit version of device specific tuned and optimized Dolby Vision 7329 capture mode. 7330 </notes> 7331 </value> 7332 <value id="0x800">DOLBY_VISION_8B_HDR_OEM_PO 7333 <notes> 7334 This is the power optimized mode for 8-bit Dolby Vision HDR device specific 7335 capture Mode. 7336 </notes> 7337 </value> 7338 <value id="0x1000">MAX 7339 <notes> 7340 </notes> 7341 </value> 7342 </enum> 7343 <description>A map of all available 10-bit dynamic range profiles along with their 7344 capture request constraints. 7345 </description> 7346 <details>Devices supporting the 10-bit output capability 7347 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7348 must list their supported dynamic range profiles. In case the camera is not able to 7349 support every possible profile combination within a single capture request, then the 7350 constraints must be listed here as well. 7351 </details> 7352 <hal_details> 7353 The array contains three entries per supported profile: 7354 1) The supported dynamic profile value. Do note that 7355 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_STANDARD is assumed to be always 7356 present and must not be listed. 7357 2) A bitmap combination of all supported profiles that can be referenced at the same 7358 time within a single capture request. Do note that a value of 0 means that there are 7359 no constraints and all combinations are supported. 7360 3) A flag indicating the presence of an internal lookahead functionality that 7361 can increase the streaming latency by more than 3 buffers. The value 0 will indicate 7362 that latency doesn't exceed 3 buffers, everything different than 0 will indicate 7363 latency that is beyond 3 buffers. In case the flag is set, then Camera clients will be 7364 advised to avoid configuring this profile for camera latency sensitive outputs such as 7365 preview. Do note, that such extra latency must not be present for the HLG10 profile. 7366 7367 For example if we assume that a device exists that can only support HLG10, HDR10 and 7368 HDR10_PLUS from the possible 10-bit profiles with the following capture constraints: 7369 1) HLG10 can be included in any capture request without constraints. 7370 2) HDR10 and HDR10_PLUS can only be referenced together and/or with HLG10 but not with 7371 STANDARD. 7372 In the same example, HLG10 and HDR10 will not have additional lookahead latency, and 7373 HDR10+ will have latency that exceeds 3 buffers. 7374 The resulting array should look like this: 7375 [ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HLG10, 0, 0, 7376 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10, 7377 (ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10 | 7378 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HLG10 | 7379 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10_PLUS), 0, 7380 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10_PLUS, 7381 (ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10_PLUS | 7382 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HLG10 | 7383 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_HDR10), 1] 7384 7385 Camera providers must ensure that each processed buffer from a stream configured with the 7386 HDR10 dynamic range profile includes SMPTE ST 2086 static metadata by calling 7387 'android::hardware::graphics::mapper::V4_0::IMapper::set' before returning the buffer. 7388 7389 Camera providers must ensure that each processed buffer from a stream configured 7390 with HDR10_PLUS dynamic range profile includes SMPTE ST 2094-40 dynamic 7391 metadata by calling 'android::hardware::graphics::mapper::V4_0::IMapper::set' before 7392 returning the buffer. 7393 7394 Camera providers must ensure that each processed buffer from a stream configured 7395 with any of the 10-bit Dolby Vision dynamic range profiles includes SMPTE ST 2094-10 7396 dynamic metadata by calling 'android::hardware::graphics::mapper::V4_0::IMapper::set' 7397 before returning the buffer. 7398 </hal_details> 7399 </entry> 7400 <entry name="recommendedTenBitDynamicRangeProfile" type="int64" visibility="java_public" 7401 optional="true" hal_version="3.8"> 7402 <description>Recommended 10-bit dynamic range profile.</description> 7403 <details>Devices supporting the 10-bit output capability 7404 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7405 must list a 10-bit supported dynamic range profile that is expected to perform 7406 optimally in terms of image quality, power and performance. 7407 The value advertised can be used as a hint by camera clients when configuring the dynamic 7408 range profile when calling 7409 {@link android.hardware.camera2.params.OutputConfiguration#setDynamicRangeProfile}. 7410 </details> 7411 </entry> 7412 <entry name="availableColorSpaceProfiles" type="int32" visibility="java_public" 7413 synthetic="true" optional="true" typedef="colorSpaceProfiles" hal_version="3.9"> 7414 <description> 7415 An interface for querying the color space profiles supported by a camera device. 7416 </description> 7417 <details> 7418 A color space profile is a combination of a color space, an image format, and a dynamic 7419 range profile. Camera clients can retrieve the list of supported color spaces by calling 7420 {@link android.hardware.camera2.params.ColorSpaceProfiles#getSupportedColorSpaces} or 7421 {@link android.hardware.camera2.params.ColorSpaceProfiles#getSupportedColorSpacesForDynamicRange}. 7422 If a camera does not support the 7423 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7424 capability, the dynamic range profile will always be 7425 {@link android.hardware.camera2.params.DynamicRangeProfiles#STANDARD}. Color space 7426 capabilities are queried in combination with an {@link android.graphics.ImageFormat}. 7427 If a camera client wants to know the general color space capabilities of a camera device 7428 regardless of image format, it can specify {@link android.graphics.ImageFormat#UNKNOWN}. 7429 The color space for a session can be configured by setting the SessionConfiguration 7430 color space via {@link android.hardware.camera2.params.SessionConfiguration#setColorSpace}. 7431 </details> 7432 </entry> 7433 <entry name="availableColorSpaceProfilesMap" type="int64" visibility="ndk_public" 7434 optional="true" enum="true" container="array" hal_version="3.9"> 7435 <array> 7436 <size>n</size> 7437 <size>3</size> 7438 </array> 7439 <enum> 7440 <value id="-1">UNSPECIFIED 7441 <notes> 7442 Default value, when not explicitly specified. The Camera device will choose the color 7443 space to employ. 7444 </notes> 7445 </value> 7446 <value visibility="system" id="0">SRGB 7447 <notes> 7448 RGB color space sRGB standardized as IEC 61966-2.1:1999. 7449 </notes> 7450 </value> 7451 <value visibility="system" id="7">DISPLAY_P3 7452 <notes> 7453 RGB color space Display P3 based on SMPTE RP 431-2-2007 and IEC 61966-2.1:1999. 7454 </notes> 7455 </value> 7456 <value visibility="system" id="16">BT2020_HLG 7457 <notes> 7458 RGB color space BT.2100 standardized as Hybrid Log Gamma encoding. 7459 </notes> 7460 </value> 7461 </enum> 7462 <description> 7463 A list of all possible color space profiles supported by a camera device. 7464 </description> 7465 <details> 7466 A color space profile is a combination of a color space, an image format, and a dynamic range 7467 profile. If a camera does not support the 7468 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 7469 capability, the dynamic range profile will always be 7470 {@link android.hardware.camera2.params.DynamicRangeProfiles#STANDARD}. Camera clients can 7471 use {@link android.hardware.camera2.params.SessionConfiguration#setColorSpace} to select 7472 a color space. 7473 </details> 7474 <hal_details> 7475 The array contains three entries per supported profile: 7476 7477 1) The supported color space. 7478 2) An image format which can be used with this color space. 7479 3) A bitmap of all compatible dynamic range profiles, if the device is HDR-capable. 7480 7481 The possible values for #1 are the positive values of the 7482 ANDROID_REQUEST_AVAILABLE_COLOR_SPACE_PROFILES_MAP_* enum, which is equivalent to 7483 {@link android.graphics.ColorSpace.Named} and its ordinals. UNSPECIFIED should not be 7484 used here. It should be noted that not all {@link android.graphics.ColorSpace.Named} 7485 values are supported, only those in the 7486 ANDROID_REQUEST_AVAILABLE_COLOR_SPACE_PROFILES_MAP_* enum. 7487 7488 The possible values for #2 consist of the public-facing image/pixel formats, found at 7489 {@link android.graphics.ImageFormat} and {@link android.graphics.PixelFormat}. Each map 7490 to a HAL pixel format except for {@link android.graphics.ImageFormat.JPEG}, 7491 {@link android.graphics.ImageFormat.HEIC}, and 7492 {@link android.graphics.ImageFormat.DEPTH_JPEG}. Depth formats besides DEPTH_JPEG are 7493 not applicable and should not be specified. If there are no constraints on the type of 7494 image format a color space is compatible with, this can be 7495 {@link android.graphics.ImageFormat.UNKNOWN}. 7496 7497 If the device is not HDR-capable, #3 should always be 7498 ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_STANDARD. Otherwise, #3 should be a 7499 bitmap of the compatible ANDROID_REQUEST_AVAILABLE_DYNAMIC_RANGE_PROFILES_* values. 7500 </hal_details> 7501 </entry> 7502 </static> 7503 </section> 7504 <section name="scaler"> 7505 <controls> 7506 <entry name="cropRegion" type="int32" visibility="public" 7507 container="array" typedef="rectangle" hwlevel="legacy"> 7508 <array> 7509 <size>4</size> 7510 </array> 7511 <description>The desired region of the sensor to read out for this capture.</description> 7512 <units>Pixel coordinates relative to 7513 android.sensor.info.activeArraySize or 7514 android.sensor.info.preCorrectionActiveArraySize depending on distortion correction 7515 capability and mode</units> 7516 <details> 7517 This control can be used to implement digital zoom. 7518 7519 For devices not supporting android.distortionCorrection.mode control, the coordinate 7520 system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being 7521 the top-left pixel of the active array. 7522 7523 For devices supporting android.distortionCorrection.mode control, the coordinate system 7524 depends on the mode being set. When the distortion correction mode is OFF, the 7525 coordinate system follows android.sensor.info.preCorrectionActiveArraySize, with `(0, 7526 0)` being the top-left pixel of the pre-correction active array. When the distortion 7527 correction mode is not OFF, the coordinate system follows 7528 android.sensor.info.activeArraySize, with `(0, 0)` being the top-left pixel of the 7529 active array. 7530 7531 Output streams use this rectangle to produce their output, cropping to a smaller region 7532 if necessary to maintain the stream's aspect ratio, then scaling the sensor input to 7533 match the output's configured resolution. 7534 7535 The crop region is usually applied after the RAW to other color space (e.g. YUV) 7536 conversion. As a result RAW streams are not croppable unless supported by the 7537 camera device. See android.scaler.availableStreamUseCases#CROPPED_RAW for details. 7538 7539 For non-raw streams, any additional per-stream cropping will be done to maximize the 7540 final pixel area of the stream. 7541 7542 For example, if the crop region is set to a 4:3 aspect ratio, then 4:3 streams will use 7543 the exact crop region. 16:9 streams will further crop vertically (letterbox). 7544 7545 Conversely, if the crop region is set to a 16:9, then 4:3 outputs will crop horizontally 7546 (pillarbox), and 16:9 streams will match exactly. These additional crops will be 7547 centered within the crop region. 7548 7549 To illustrate, here are several scenarios of different crop regions and output streams, 7550 for a hypothetical camera device with an active array of size `(2000,1500)`. Note that 7551 several of these examples use non-centered crop regions for ease of illustration; such 7552 regions are only supported on devices with FREEFORM capability 7553 (android.scaler.croppingType `== FREEFORM`), but this does not affect the way the crop 7554 rules work otherwise. 7555 7556 * Camera Configuration: 7557 * Active array size: `2000x1500` (3 MP, 4:3 aspect ratio) 7558 * Output stream #1: `640x480` (VGA, 4:3 aspect ratio) 7559 * Output stream #2: `1280x720` (720p, 16:9 aspect ratio) 7560 * Case #1: 4:3 crop region with 2x digital zoom 7561 * Crop region: `Rect(500, 375, 1500, 1125) // (left, top, right, bottom)` 7562 *  7563 * `640x480` stream source area: `(500, 375, 1500, 1125)` (equal to crop region) 7564 * `1280x720` stream source area: `(500, 469, 1500, 1031)` (letterboxed) 7565 * Case #2: 16:9 crop region with ~1.5x digital zoom. 7566 * Crop region: `Rect(500, 375, 1833, 1125)` 7567 *  7568 * `640x480` stream source area: `(666, 375, 1666, 1125)` (pillarboxed) 7569 * `1280x720` stream source area: `(500, 375, 1833, 1125)` (equal to crop region) 7570 * Case #3: 1:1 crop region with ~2.6x digital zoom. 7571 * Crop region: `Rect(500, 375, 1250, 1125)` 7572 *  7573 * `640x480` stream source area: `(500, 469, 1250, 1031)` (letterboxed) 7574 * `1280x720` stream source area: `(500, 543, 1250, 957)` (letterboxed) 7575 * Case #4: Replace `640x480` stream with `1024x1024` stream, with 4:3 crop region: 7576 * Crop region: `Rect(500, 375, 1500, 1125)` 7577 *  7578 * `1024x1024` stream source area: `(625, 375, 1375, 1125)` (pillarboxed) 7579 * `1280x720` stream source area: `(500, 469, 1500, 1031)` (letterboxed) 7580 * Note that in this case, neither of the two outputs is a subset of the other, with 7581 each containing image data the other doesn't have. 7582 7583 If the coordinate system is android.sensor.info.activeArraySize, the width and height 7584 of the crop region cannot be set to be smaller than 7585 `floor( activeArraySize.width / android.scaler.availableMaxDigitalZoom )` and 7586 `floor( activeArraySize.height / android.scaler.availableMaxDigitalZoom )`, respectively. 7587 7588 If the coordinate system is android.sensor.info.preCorrectionActiveArraySize, the width 7589 and height of the crop region cannot be set to be smaller than 7590 `floor( preCorrectionActiveArraySize.width / android.scaler.availableMaxDigitalZoom )` 7591 and 7592 `floor( preCorrectionActiveArraySize.height / android.scaler.availableMaxDigitalZoom )`, 7593 respectively. 7594 7595 The camera device may adjust the crop region to account for rounding and other hardware 7596 requirements; the final crop region used will be included in the output capture result. 7597 7598 The camera sensor output aspect ratio depends on factors such as output stream 7599 combination and android.control.aeTargetFpsRange, and shouldn't be adjusted by using 7600 this control. And the camera device will treat different camera sensor output sizes 7601 (potentially with in-sensor crop) as the same crop of 7602 android.sensor.info.activeArraySize. As a result, the application shouldn't assume the 7603 maximum crop region always maps to the same aspect ratio or field of view for the 7604 sensor output. 7605 7606 Starting from API level 30, it's strongly recommended to use android.control.zoomRatio 7607 to take advantage of better support for zoom with logical multi-camera. The benefits 7608 include better precision with optical-digital zoom combination, and ability to do 7609 zoom-out from 1.0x. When using android.control.zoomRatio for zoom, the crop region in 7610 the capture request should be left as the default activeArray size. The 7611 coordinate system is post-zoom, meaning that the activeArraySize or 7612 preCorrectionActiveArraySize covers the camera device's field of view "after" zoom. See 7613 android.control.zoomRatio for details. 7614 7615 For camera devices with the 7616 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 7617 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 7618 lists {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode} 7619 7620 android.sensor.info.activeArraySizeMaximumResolution / 7621 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 7622 coordinate system for requests where android.sensor.pixelMode is set to 7623 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 7624 </details> 7625 <ndk_details> 7626 The data representation is int[4], which maps to (left, top, width, height). 7627 </ndk_details> 7628 <hal_details> 7629 The output streams must maintain square pixels at all 7630 times, no matter what the relative aspect ratios of the 7631 crop region and the stream are. Negative values for 7632 corner are allowed for raw output if full pixel array is 7633 larger than active pixel array. Width and height may be 7634 rounded to nearest larger supportable width, especially 7635 for raw output, where only a few fixed scales may be 7636 possible. 7637 7638 If android.control.zoomRatio is supported by the HAL, the HAL must report the zoom 7639 ratio via android.control.zoomRatio, and change the coordinate system such that 7640 android.sensor.info.preCorrectionActiveArraySize or android.sensor.info.activeArraySize 7641 (depending on whether android.distortionCorrection.mode is supported) is used to 7642 represent the camera field-of-view after zoom. see android.control.zoomRatio for 7643 details. 7644 7645 HAL2.x uses only (x, y, width) 7646 </hal_details> 7647 <tag id="BC" /> 7648 </entry> 7649 </controls> 7650 <static> 7651 <entry name="availableFormats" type="int32" 7652 visibility="hidden" deprecated="true" enum="true" 7653 container="array" typedef="imageFormat"> 7654 <array> 7655 <size>n</size> 7656 </array> 7657 <enum> 7658 <value optional="true" id="0x20">RAW16 7659 <notes> 7660 RAW16 is a standard, cross-platform format for raw image 7661 buffers with 16-bit pixels. 7662 7663 Buffers of this format are typically expected to have a 7664 Color Filter Array (CFA) layout, which is given in 7665 android.sensor.info.colorFilterArrangement. Sensors with 7666 CFAs that are not representable by a format in 7667 android.sensor.info.colorFilterArrangement should not 7668 use this format. 7669 7670 Buffers of this format will also follow the constraints given for 7671 RAW_OPAQUE buffers, but with relaxed performance constraints. 7672 7673 This format is intended to give users access to the full contents 7674 of the buffers coming directly from the image sensor prior to any 7675 cropping or scaling operations, and all coordinate systems for 7676 metadata used for this format are relative to the size of the 7677 active region of the image sensor before any geometric distortion 7678 correction has been applied (i.e. 7679 android.sensor.info.preCorrectionActiveArraySize). Supported 7680 dimensions for this format are limited to the full dimensions of 7681 the sensor (e.g. either android.sensor.info.pixelArraySize or 7682 android.sensor.info.preCorrectionActiveArraySize will be the 7683 only supported output size). 7684 7685 See android.scaler.availableInputOutputFormatsMap for 7686 the full set of performance guarantees. 7687 </notes> 7688 </value> 7689 <value optional="true" id="0x24">RAW_OPAQUE 7690 <notes> 7691 RAW_OPAQUE (or 7692 {@link android.graphics.ImageFormat#RAW_PRIVATE RAW_PRIVATE} 7693 as referred in public API) is a format for raw image buffers 7694 coming from an image sensor. 7695 7696 The actual structure of buffers of this format is 7697 platform-specific, but must follow several constraints: 7698 7699 1. No image post-processing operations may have been applied to 7700 buffers of this type. These buffers contain raw image data coming 7701 directly from the image sensor. 7702 1. If a buffer of this format is passed to the camera device for 7703 reprocessing, the resulting images will be identical to the images 7704 produced if the buffer had come directly from the sensor and was 7705 processed with the same settings. 7706 7707 The intended use for this format is to allow access to the native 7708 raw format buffers coming directly from the camera sensor without 7709 any additional conversions or decrease in framerate. 7710 7711 See android.scaler.availableInputOutputFormatsMap for the full set of 7712 performance guarantees. 7713 </notes> 7714 </value> 7715 <value optional="true" id="0x32315659">YV12 7716 <notes>YCrCb 4:2:0 Planar</notes> 7717 </value> 7718 <value optional="true" id="0x11">YCrCb_420_SP 7719 <notes>NV21</notes> 7720 </value> 7721 <value id="0x22">IMPLEMENTATION_DEFINED 7722 <notes>System internal format, not application-accessible</notes> 7723 </value> 7724 <value id="0x23">YCbCr_420_888 7725 <notes>Flexible YUV420 Format</notes> 7726 </value> 7727 <value id="0x21">BLOB 7728 <notes>JPEG format</notes> 7729 </value> 7730 <value id="0x25" hal_version="3.4">RAW10 7731 <notes>RAW10</notes> 7732 </value> 7733 <value id="0x26" hal_version="3.4">RAW12 7734 <notes>RAW12</notes> 7735 </value> 7736 <value id="0x20203859" hal_version="3.4">Y8 7737 <notes>Y8</notes> 7738 </value> 7739 </enum> 7740 <description>The list of image formats that are supported by this 7741 camera device for output streams.</description> 7742 <deprecation_description> 7743 Not used in HALv3 or newer 7744 </deprecation_description> 7745 <details> 7746 All camera devices will support JPEG and YUV_420_888 formats. 7747 7748 When set to YUV_420_888, application can access the YUV420 data directly. 7749 </details> 7750 <hal_details> 7751 These format values are from HAL_PIXEL_FORMAT_* in 7752 system/core/libsystem/include/system/graphics-base.h. 7753 7754 When IMPLEMENTATION_DEFINED is used, the platform 7755 gralloc module will select a format based on the usage flags provided 7756 by the camera HAL device and the other endpoint of the stream. It is 7757 usually used by preview and recording streams, where the application doesn't 7758 need access the image data. 7759 7760 YCbCr_420_888 format must be supported by the HAL. When an image stream 7761 needs CPU/application direct access, this format will be used. For a MONOCHROME 7762 camera device, the pixel value of Cb and Cr planes is 128. 7763 7764 The BLOB format must be supported by the HAL. This is used for the JPEG stream. 7765 7766 A RAW_OPAQUE buffer should contain only pixel data. It is strongly 7767 recommended that any information used by the camera device when 7768 processing images is fully expressed by the result metadata 7769 for that image buffer. 7770 </hal_details> 7771 <tag id="BC" /> 7772 </entry> 7773 <entry name="availableJpegMinDurations" type="int64" visibility="hidden" deprecated="true" 7774 container="array"> 7775 <array> 7776 <size>n</size> 7777 </array> 7778 <description>The minimum frame duration that is supported 7779 for each resolution in android.scaler.availableJpegSizes. 7780 </description> 7781 <deprecation_description> 7782 Not used in HALv3 or newer 7783 </deprecation_description> 7784 <units>Nanoseconds</units> 7785 <range>TODO: Remove property.</range> 7786 <details> 7787 This corresponds to the minimum steady-state frame duration when only 7788 that JPEG stream is active and captured in a burst, with all 7789 processing (typically in android.*.mode) set to FAST. 7790 7791 When multiple streams are configured, the minimum 7792 frame duration will be &gt;= max(individual stream min 7793 durations)</details> 7794 <tag id="BC" /> 7795 </entry> 7796 <entry name="availableJpegSizes" type="int32" visibility="hidden" 7797 deprecated="true" container="array" typedef="size"> 7798 <array> 7799 <size>n</size> 7800 <size>2</size> 7801 </array> 7802 <description>The JPEG resolutions that are supported by this camera device.</description> 7803 <deprecation_description> 7804 Not used in HALv3 or newer 7805 </deprecation_description> 7806 <range>TODO: Remove property.</range> 7807 <details> 7808 The resolutions are listed as `(width, height)` pairs. All camera devices will support 7809 sensor maximum resolution (defined by android.sensor.info.activeArraySize). 7810 </details> 7811 <hal_details> 7812 The HAL must include sensor maximum resolution 7813 (defined by android.sensor.info.activeArraySize), 7814 and should include half/quarter of sensor maximum resolution. 7815 </hal_details> 7816 <tag id="BC" /> 7817 </entry> 7818 <entry name="availableMaxDigitalZoom" type="float" visibility="public" 7819 hwlevel="legacy" session_characteristics_key_since="35"> 7820 <description>The maximum ratio between both active area width 7821 and crop region width, and active area height and 7822 crop region height, for android.scaler.cropRegion. 7823 </description> 7824 <units>Zoom scale factor</units> 7825 <range>&gt;=1</range> 7826 <details> 7827 This represents the maximum amount of zooming possible by 7828 the camera device, or equivalently, the minimum cropping 7829 window size. 7830 7831 Crop regions that have a width or height that is smaller 7832 than this ratio allows will be rounded up to the minimum 7833 allowed size by the camera device. 7834 7835 Starting from API level 30, when using android.control.zoomRatio to zoom in or out, 7836 the application must use android.control.zoomRatioRange to query both the minimum and 7837 maximum zoom ratio. 7838 </details> 7839 <hal_details> 7840 If the HAL supports android.control.zoomRatio, this value must be equal to or less than 7841 the maximum supported zoomRatio specified in android.control.zoomRatioRange. 7842 </hal_details> 7843 <tag id="BC" /> 7844 </entry> 7845 <entry name="availableProcessedMinDurations" type="int64" visibility="hidden" deprecated="true" 7846 container="array"> 7847 <array> 7848 <size>n</size> 7849 </array> 7850 <description>For each available processed output size (defined in 7851 android.scaler.availableProcessedSizes), this property lists the 7852 minimum supportable frame duration for that size. 7853 </description> 7854 <deprecation_description> 7855 Not used in HALv3 or newer 7856 </deprecation_description> 7857 <units>Nanoseconds</units> 7858 <details> 7859 This should correspond to the frame duration when only that processed 7860 stream is active, with all processing (typically in android.*.mode) 7861 set to FAST. 7862 7863 When multiple streams are configured, the minimum frame duration will 7864 be &gt;= max(individual stream min durations). 7865 </details> 7866 <tag id="BC" /> 7867 </entry> 7868 <entry name="availableProcessedSizes" type="int32" visibility="hidden" 7869 deprecated="true" container="array" typedef="size"> 7870 <array> 7871 <size>n</size> 7872 <size>2</size> 7873 </array> 7874 <description>The resolutions available for use with 7875 processed output streams, such as YV12, NV12, and 7876 platform opaque YUV/RGB streams to the GPU or video 7877 encoders.</description> 7878 <deprecation_description> 7879 Not used in HALv3 or newer 7880 </deprecation_description> 7881 <details> 7882 The resolutions are listed as `(width, height)` pairs. 7883 7884 For a given use case, the actual maximum supported resolution 7885 may be lower than what is listed here, depending on the destination 7886 Surface for the image data. For example, for recording video, 7887 the video encoder chosen may have a maximum size limit (e.g. 1080p) 7888 smaller than what the camera (e.g. maximum resolution is 3264x2448) 7889 can provide. 7890 7891 Please reference the documentation for the image data destination to 7892 check if it limits the maximum size for image data. 7893 </details> 7894 <hal_details> 7895 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 7896 the HAL must include all JPEG sizes listed in android.scaler.availableJpegSizes 7897 and each below resolution if it is smaller than or equal to the sensor 7898 maximum resolution (if they are not listed in JPEG sizes already): 7899 7900 * 240p (320 x 240) 7901 * 480p (640 x 480) 7902 * 720p (1280 x 720) 7903 * 1080p (1920 x 1080) 7904 7905 For LIMITED capability devices (`android.info.supportedHardwareLevel == LIMITED`), 7906 the HAL only has to list up to the maximum video size supported by the devices. 7907 </hal_details> 7908 <tag id="BC" /> 7909 </entry> 7910 <entry name="availableRawMinDurations" type="int64" deprecated="true" 7911 container="array"> 7912 <array> 7913 <size>n</size> 7914 </array> 7915 <description> 7916 For each available raw output size (defined in 7917 android.scaler.availableRawSizes), this property lists the minimum 7918 supportable frame duration for that size. 7919 </description> 7920 <deprecation_description> 7921 Not used in HALv3 or newer 7922 </deprecation_description> 7923 <units>Nanoseconds</units> 7924 <details> 7925 Should correspond to the frame duration when only the raw stream is 7926 active. 7927 7928 When multiple streams are configured, the minimum 7929 frame duration will be &gt;= max(individual stream min 7930 durations)</details> 7931 <tag id="BC" /> 7932 </entry> 7933 <entry name="availableRawSizes" type="int32" deprecated="true" 7934 container="array" typedef="size"> 7935 <array> 7936 <size>n</size> 7937 <size>2</size> 7938 </array> 7939 <description>The resolutions available for use with raw 7940 sensor output streams, listed as width, 7941 height</description> 7942 <deprecation_description> 7943 Not used in HALv3 or newer 7944 </deprecation_description> 7945 </entry> 7946 </static> 7947 <dynamic> 7948 <clone entry="android.scaler.cropRegion" kind="controls"> 7949 </clone> 7950 </dynamic> 7951 <static> 7952 <entry name="availableInputOutputFormatsMap" type="int32" visibility="hidden" 7953 typedef="reprocessFormatsMap"> 7954 <description>The mapping of image formats that are supported by this 7955 camera device for input streams, to their corresponding output formats. 7956 </description> 7957 <details> 7958 All camera devices with at least 1 7959 android.request.maxNumInputStreams will have at least one 7960 available input format. 7961 7962 The camera device will support the following map of formats, 7963 if its dependent capability (android.request.availableCapabilities) is supported: 7964 7965 Input Format | Output Format | Capability 7966 :-------------------------------------------------|:--------------------------------------------------|:---------- 7967 {@link android.graphics.ImageFormat#PRIVATE} | {@link android.graphics.ImageFormat#JPEG} | PRIVATE_REPROCESSING 7968 {@link android.graphics.ImageFormat#PRIVATE} | {@link android.graphics.ImageFormat#YUV_420_888} | PRIVATE_REPROCESSING 7969 {@link android.graphics.ImageFormat#YUV_420_888} | {@link android.graphics.ImageFormat#JPEG} | YUV_REPROCESSING 7970 {@link android.graphics.ImageFormat#YUV_420_888} | {@link android.graphics.ImageFormat#YUV_420_888} | YUV_REPROCESSING 7971 7972 PRIVATE refers to a device-internal format that is not directly application-visible. A 7973 PRIVATE input surface can be acquired by {@link android.media.ImageReader#newInstance} 7974 with {@link android.graphics.ImageFormat#PRIVATE} as the format. 7975 7976 For a PRIVATE_REPROCESSING-capable camera device, using the PRIVATE format as either input 7977 or output will never hurt maximum frame rate (i.e. {@link 7978 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration 7979 getOutputStallDuration(ImageFormat.PRIVATE, size)} is always 0), 7980 7981 Attempting to configure an input stream with output streams not 7982 listed as available in this map is not valid. 7983 7984 Additionally, if the camera device is MONOCHROME with Y8 support, it will also support 7985 the following map of formats if its dependent capability 7986 (android.request.availableCapabilities) is supported: 7987 7988 Input Format | Output Format | Capability 7989 :-------------------------------------------------|:--------------------------------------------------|:---------- 7990 {@link android.graphics.ImageFormat#PRIVATE} | {@link android.graphics.ImageFormat#Y8} | PRIVATE_REPROCESSING 7991 {@link android.graphics.ImageFormat#Y8} | {@link android.graphics.ImageFormat#JPEG} | YUV_REPROCESSING 7992 {@link android.graphics.ImageFormat#Y8} | {@link android.graphics.ImageFormat#Y8} | YUV_REPROCESSING 7993 7994 </details> 7995 <hal_details> 7996 For the formats, see `system/core/libsystem/include/system/graphics-base.h` for a 7997 definition of the image format enumerations. The PRIVATE format refers to the 7998 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED format. The HAL could determine 7999 the actual format by using the gralloc usage flags. 8000 For ZSL use case in particular, the HAL could choose appropriate format (partially 8001 processed YUV or RAW based format) by checking the format and GRALLOC_USAGE_HW_CAMERA_ZSL. 8002 See camera3.h for more details. 8003 8004 This value is encoded as a variable-size array-of-arrays. 8005 The inner array always contains `[format, length, ...]` where 8006 `...` has `length` elements. An inner array is followed by another 8007 inner array if the total metadata entry size hasn't yet been exceeded. 8008 8009 A code sample to read/write this encoding (with a device that 8010 supports reprocessing IMPLEMENTATION_DEFINED to YUV_420_888, and JPEG, 8011 and reprocessing YUV_420_888 to YUV_420_888 and JPEG): 8012 8013 // reading 8014 int32_t* contents = &entry.i32[0]; 8015 for (size_t i = 0; i < entry.count; ) { 8016 int32_t format = contents[i++]; 8017 int32_t length = contents[i++]; 8018 int32_t output_formats[length]; 8019 memcpy(&output_formats[0], &contents[i], 8020 length * sizeof(int32_t)); 8021 i += length; 8022 } 8023 8024 // writing (static example, PRIVATE_REPROCESSING + YUV_REPROCESSING) 8025 int32_t[] contents = { 8026 IMPLEMENTATION_DEFINED, 2, YUV_420_888, BLOB, 8027 YUV_420_888, 2, YUV_420_888, BLOB, 8028 }; 8029 update_camera_metadata_entry(metadata, index, &contents[0], 8030 sizeof(contents)/sizeof(contents[0]), &updated_entry); 8031 8032 If the HAL claims to support any of the capabilities listed in the 8033 above details, then it must also support all the input-output 8034 combinations listed for that capability. It can optionally support 8035 additional formats if it so chooses. 8036 </hal_details> 8037 <tag id="REPROC" /> 8038 </entry> 8039 <entry name="availableStreamConfigurations" type="int32" visibility="ndk_public" 8040 enum="true" container="array" typedef="streamConfiguration" hwlevel="legacy"> 8041 <array> 8042 <size>n</size> 8043 <size>4</size> 8044 </array> 8045 <enum> 8046 <value>OUTPUT</value> 8047 <value>INPUT</value> 8048 </enum> 8049 <description>The available stream configurations that this 8050 camera device supports 8051 (i.e. format, width, height, output/input stream). 8052 </description> 8053 <details> 8054 The configurations are listed as `(format, width, height, input?)` 8055 tuples. 8056 8057 For a given use case, the actual maximum supported resolution 8058 may be lower than what is listed here, depending on the destination 8059 Surface for the image data. For example, for recording video, 8060 the video encoder chosen may have a maximum size limit (e.g. 1080p) 8061 smaller than what the camera (e.g. maximum resolution is 3264x2448) 8062 can provide. 8063 8064 Please reference the documentation for the image data destination to 8065 check if it limits the maximum size for image data. 8066 8067 Not all output formats may be supported in a configuration with 8068 an input stream of a particular format. For more details, see 8069 android.scaler.availableInputOutputFormatsMap. 8070 8071 For applications targeting SDK version older than 31, the following table 8072 describes the minimum required output stream configurations based on the hardware level 8073 (android.info.supportedHardwareLevel): 8074 8075 Format | Size | Hardware Level | Notes 8076 :-------------:|:--------------------------------------------:|:--------------:|:--------------: 8077 JPEG | android.sensor.info.activeArraySize | Any | 8078 JPEG | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 8079 JPEG | 1280x720 (720) | Any | if 720p <= activeArraySize 8080 JPEG | 640x480 (480p) | Any | if 480p <= activeArraySize 8081 JPEG | 320x240 (240p) | Any | if 240p <= activeArraySize 8082 YUV_420_888 | all output sizes available for JPEG | FULL | 8083 YUV_420_888 | all output sizes available for JPEG, up to the maximum video size | LIMITED | 8084 IMPLEMENTATION_DEFINED | same as YUV_420_888 | Any | 8085 8086 For applications targeting SDK version 31 or newer, if the mobile device declares to be 8087 media performance class 12 or higher by setting 8088 {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 8089 the primary camera devices (first rear/front camera in the camera ID list) will not 8090 support JPEG sizes smaller than 1080p. If the application configures a JPEG stream 8091 smaller than 1080p, the camera device will round up the JPEG image size to at least 8092 1080p. The requirements for IMPLEMENTATION_DEFINED and YUV_420_888 stay the same. 8093 This new minimum required output stream configurations are illustrated by the table below: 8094 8095 Format | Size | Hardware Level | Notes 8096 :-------------:|:--------------------------------------------:|:--------------:|:--------------: 8097 JPEG | android.sensor.info.activeArraySize | Any | 8098 JPEG | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 8099 YUV_420_888 | android.sensor.info.activeArraySize | FULL | 8100 YUV_420_888 | 1920x1080 (1080p) | FULL | if 1080p <= activeArraySize 8101 YUV_420_888 | 1280x720 (720) | FULL | if 720p <= activeArraySize 8102 YUV_420_888 | 640x480 (480p) | FULL | if 480p <= activeArraySize 8103 YUV_420_888 | 320x240 (240p) | FULL | if 240p <= activeArraySize 8104 YUV_420_888 | all output sizes available for FULL hardware level, up to the maximum video size | LIMITED | 8105 IMPLEMENTATION_DEFINED | same as YUV_420_888 | Any | 8106 8107 For applications targeting SDK version 31 or newer, if the mobile device doesn't declare 8108 to be media performance class 12 or better by setting 8109 {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 8110 or if the camera device isn't a primary rear/front camera, the minimum required output 8111 stream configurations are the same as for applications targeting SDK version older than 8112 31. 8113 8114 Refer to android.request.availableCapabilities for additional 8115 mandatory stream configurations on a per-capability basis. 8116 8117 Exception on 176x144 (QCIF) resolution: camera devices usually have a fixed capability for 8118 downscaling from larger resolution to smaller, and the QCIF resolution sometimes is not 8119 fully supported due to this limitation on devices with high-resolution image sensors. 8120 Therefore, trying to configure a QCIF resolution stream together with any other 8121 stream larger than 1920x1080 resolution (either width or height) might not be supported, 8122 and capture session creation will fail if it is not. 8123 8124 </details> 8125 <hal_details> 8126 It is recommended (but not mandatory) to also include half/quarter 8127 of sensor maximum resolution for JPEG formats (regardless of hardware 8128 level). 8129 8130 (The following is a rewording of the above required table): 8131 8132 For JPEG format, the sizes may be restricted by below conditions: 8133 8134 * The HAL may choose the aspect ratio of each Jpeg size to be one of well known ones 8135 (e.g. 4:3, 16:9, 3:2 etc.). If the sensor maximum resolution 8136 (defined by android.sensor.info.activeArraySize) has an aspect ratio other than these, 8137 it does not have to be included in the supported JPEG sizes. 8138 * Some hardware JPEG encoders may have pixel boundary alignment requirements, such as 8139 the dimensions being a multiple of 16. 8140 8141 Therefore, the maximum JPEG size may be smaller than sensor maximum resolution. 8142 However, the largest JPEG size must be as close as possible to the sensor maximum 8143 resolution given above constraints. It is required that after aspect ratio adjustments, 8144 additional size reduction due to other issues must be less than 3% in area. For example, 8145 if the sensor maximum resolution is 3280x2464, if the maximum JPEG size has aspect 8146 ratio 4:3, the JPEG encoder alignment requirement is 16, the maximum JPEG size will be 8147 3264x2448. 8148 8149 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 8150 the HAL must include all YUV_420_888 sizes that have JPEG sizes listed 8151 here as output streams. 8152 8153 It must also include each below resolution if it is smaller than or 8154 equal to the sensor maximum resolution (for both YUV_420_888 and JPEG 8155 formats), as output streams: 8156 8157 * 240p (320 x 240) 8158 * 480p (640 x 480) 8159 * 720p (1280 x 720) 8160 * 1080p (1920 x 1080) 8161 8162 Note that for primary cameras (first rear/front facing camera in the camera ID list) 8163 on a device with {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} set to 8164 31 or larger, camera framework filters out JPEG sizes smaller than 1080p depending on 8165 applications' targetSdkLevel. The camera HAL must still support the smaller JPEG sizes 8166 to maintain backward compatibility. 8167 8168 For LIMITED capability devices 8169 (`android.info.supportedHardwareLevel == LIMITED`), 8170 the HAL only has to list up to the maximum video size 8171 supported by the device. 8172 8173 Regardless of hardware level, every output resolution available for 8174 YUV_420_888 must also be available for IMPLEMENTATION_DEFINED. 8175 8176 This supersedes the following fields, which are now deprecated: 8177 8178 * availableFormats 8179 * available[Processed,Raw,Jpeg]Sizes 8180 </hal_details> 8181 </entry> 8182 <entry name="availableMinFrameDurations" type="int64" visibility="ndk_public" 8183 container="array" typedef="streamConfigurationDuration" hwlevel="legacy"> 8184 <array> 8185 <size>4</size> 8186 <size>n</size> 8187 </array> 8188 <description>This lists the minimum frame duration for each 8189 format/size combination. 8190 </description> 8191 <units>(format, width, height, ns) x n</units> 8192 <details> 8193 This should correspond to the frame duration when only that 8194 stream is active, with all processing (typically in android.*.mode) 8195 set to either OFF or FAST. 8196 8197 When multiple streams are used in a request, the minimum frame 8198 duration will be max(individual stream min durations). 8199 8200 See android.sensor.frameDuration and 8201 android.scaler.availableStallDurations for more details about 8202 calculating the max frame rate. 8203 </details> 8204 <tag id="V1" /> 8205 </entry> 8206 <entry name="availableStallDurations" type="int64" visibility="ndk_public" 8207 container="array" typedef="streamConfigurationDuration" hwlevel="legacy"> 8208 <array> 8209 <size>4</size> 8210 <size>n</size> 8211 </array> 8212 <description>This lists the maximum stall duration for each 8213 output format/size combination. 8214 </description> 8215 <units>(format, width, height, ns) x n</units> 8216 <details> 8217 A stall duration is how much extra time would get added 8218 to the normal minimum frame duration for a repeating request 8219 that has streams with non-zero stall. 8220 8221 For example, consider JPEG captures which have the following 8222 characteristics: 8223 8224 * JPEG streams act like processed YUV streams in requests for which 8225 they are not included; in requests in which they are directly 8226 referenced, they act as JPEG streams. This is because supporting a 8227 JPEG stream requires the underlying YUV data to always be ready for 8228 use by a JPEG encoder, but the encoder will only be used (and impact 8229 frame duration) on requests that actually reference a JPEG stream. 8230 * The JPEG processor can run concurrently to the rest of the camera 8231 pipeline, but cannot process more than 1 capture at a time. 8232 8233 In other words, using a repeating YUV request would result 8234 in a steady frame rate (let's say it's 30 FPS). If a single 8235 JPEG request is submitted periodically, the frame rate will stay 8236 at 30 FPS (as long as we wait for the previous JPEG to return each 8237 time). If we try to submit a repeating YUV + JPEG request, then 8238 the frame rate will drop from 30 FPS. 8239 8240 In general, submitting a new request with a non-0 stall time 8241 stream will _not_ cause a frame rate drop unless there are still 8242 outstanding buffers for that stream from previous requests. 8243 8244 Submitting a repeating request with streams (call this `S`) 8245 is the same as setting the minimum frame duration from 8246 the normal minimum frame duration corresponding to `S`, added with 8247 the maximum stall duration for `S`. 8248 8249 If interleaving requests with and without a stall duration, 8250 a request will stall by the maximum of the remaining times 8251 for each can-stall stream with outstanding buffers. 8252 8253 This means that a stalling request will not have an exposure start 8254 until the stall has completed. 8255 8256 This should correspond to the stall duration when only that stream is 8257 active, with all processing (typically in android.*.mode) set to FAST 8258 or OFF. Setting any of the processing modes to HIGH_QUALITY 8259 effectively results in an indeterminate stall duration for all 8260 streams in a request (the regular stall calculation rules are 8261 ignored). 8262 8263 The following formats may always have a stall duration: 8264 8265 * {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG} 8266 * {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16} 8267 8268 The following formats will never have a stall duration: 8269 8270 * {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888} 8271 * {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10} 8272 * {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12} 8273 * {@link android.graphics.ImageFormat#Y8|AIMAGE_FORMAT_Y8} 8274 8275 All other formats may or may not have an allowed stall duration on 8276 a per-capability basis; refer to android.request.availableCapabilities 8277 for more details. 8278 8279 See android.sensor.frameDuration for more information about 8280 calculating the max frame rate (absent stalls). 8281 </details> 8282 <hal_details> 8283 If possible, it is recommended that all non-JPEG formats 8284 (such as RAW16) should not have a stall duration. RAW10, RAW12, RAW_OPAQUE 8285 and IMPLEMENTATION_DEFINED must not have stall durations. 8286 </hal_details> 8287 <tag id="V1" /> 8288 </entry> 8289 <entry name="streamConfigurationMap" type="int32" visibility="java_public" 8290 synthetic="true" typedef="streamConfigurationMap" 8291 hwlevel="legacy"> 8292 <description>The available stream configurations that this 8293 camera device supports; also includes the minimum frame durations 8294 and the stall durations for each format/size combination. 8295 </description> 8296 <details> 8297 All camera devices will support sensor maximum resolution (defined by 8298 android.sensor.info.activeArraySize) for the JPEG format. 8299 8300 For a given use case, the actual maximum supported resolution 8301 may be lower than what is listed here, depending on the destination 8302 Surface for the image data. For example, for recording video, 8303 the video encoder chosen may have a maximum size limit (e.g. 1080p) 8304 smaller than what the camera (e.g. maximum resolution is 3264x2448) 8305 can provide. 8306 8307 Please reference the documentation for the image data destination to 8308 check if it limits the maximum size for image data. 8309 8310 For applications targeting SDK version older than 31, the following table 8311 describes the minimum required output stream configurations based on the 8312 hardware level (android.info.supportedHardwareLevel): 8313 8314 Format | Size | Hardware Level | Notes 8315 :-------------------------------------------------:|:--------------------------------------------:|:--------------:|:--------------: 8316 {@link android.graphics.ImageFormat#JPEG} | android.sensor.info.activeArraySize (*1) | Any | 8317 {@link android.graphics.ImageFormat#JPEG} | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 8318 {@link android.graphics.ImageFormat#JPEG} | 1280x720 (720p) | Any | if 720p <= activeArraySize 8319 {@link android.graphics.ImageFormat#JPEG} | 640x480 (480p) | Any | if 480p <= activeArraySize 8320 {@link android.graphics.ImageFormat#JPEG} | 320x240 (240p) | Any | if 240p <= activeArraySize 8321 {@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for JPEG | FULL | 8322 {@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for JPEG, up to the maximum video size | LIMITED | 8323 {@link android.graphics.ImageFormat#PRIVATE} | same as YUV_420_888 | Any | 8324 8325 For applications targeting SDK version 31 or newer, if the mobile device declares to be 8326 media performance class 12 or higher by setting 8327 {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 8328 the primary camera devices (first rear/front camera in the camera ID list) will not 8329 support JPEG sizes smaller than 1080p. If the application configures a JPEG stream 8330 smaller than 1080p, the camera device will round up the JPEG image size to at least 8331 1080p. The requirements for IMPLEMENTATION_DEFINED and YUV_420_888 stay the same. 8332 This new minimum required output stream configurations are illustrated by the table below: 8333 8334 Format | Size | Hardware Level | Notes 8335 :-------------------------------------------------:|:--------------------------------------------:|:--------------:|:--------------: 8336 {@link android.graphics.ImageFormat#JPEG} | android.sensor.info.activeArraySize (*1) | Any | 8337 {@link android.graphics.ImageFormat#JPEG} | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 8338 {@link android.graphics.ImageFormat#YUV_420_888} | android.sensor.info.activeArraySize | FULL | 8339 {@link android.graphics.ImageFormat#YUV_420_888} | 1920x1080 (1080p) | FULL | if 1080p <= activeArraySize 8340 {@link android.graphics.ImageFormat#YUV_420_888} | 1280x720 (720) | FULL | if 720p <= activeArraySize 8341 {@link android.graphics.ImageFormat#YUV_420_888} | 640x480 (480p) | FULL | if 480p <= activeArraySize 8342 {@link android.graphics.ImageFormat#YUV_420_888} | 320x240 (240p) | FULL | if 240p <= activeArraySize 8343 {@link android.graphics.ImageFormat#YUV_420_888} | all output sizes available for FULL hardware level, up to the maximum video size | LIMITED | 8344 {@link android.graphics.ImageFormat#PRIVATE} | same as YUV_420_888 | Any | 8345 8346 For applications targeting SDK version 31 or newer, if the mobile device doesn't declare 8347 to be media performance class 12 or better by setting 8348 {@link android.os.Build.VERSION#MEDIA_PERFORMANCE_CLASS} to be 31 or larger, 8349 or if the camera device isn't a primary rear/front camera, the minimum required output 8350 stream configurations are the same as for applications targeting SDK version older than 8351 31. 8352 8353 Refer to android.request.availableCapabilities and 8354 [the table](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations) 8355 for additional mandatory stream configurations on a per-capability basis. 8356 8357 *1: For JPEG format, the sizes may be restricted by below conditions: 8358 8359 * The HAL may choose the aspect ratio of each Jpeg size to be one of well known ones 8360 (e.g. 4:3, 16:9, 3:2 etc.). If the sensor maximum resolution 8361 (defined by android.sensor.info.activeArraySize) has an aspect ratio other than these, 8362 it does not have to be included in the supported JPEG sizes. 8363 * Some hardware JPEG encoders may have pixel boundary alignment requirements, such as 8364 the dimensions being a multiple of 16. 8365 Therefore, the maximum JPEG size may be smaller than sensor maximum resolution. 8366 However, the largest JPEG size will be as close as possible to the sensor maximum 8367 resolution given above constraints. It is required that after aspect ratio adjustments, 8368 additional size reduction due to other issues must be less than 3% in area. For example, 8369 if the sensor maximum resolution is 3280x2464, if the maximum JPEG size has aspect 8370 ratio 4:3, and the JPEG encoder alignment requirement is 16, the maximum JPEG size will be 8371 3264x2448. 8372 8373 Exception on 176x144 (QCIF) resolution: camera devices usually have a fixed capability on 8374 downscaling from larger resolution to smaller ones, and the QCIF resolution can sometimes 8375 not be fully supported due to this limitation on devices with high-resolution image 8376 sensors. Therefore, trying to configure a QCIF resolution stream together with any other 8377 stream larger than 1920x1080 resolution (either width or height) might not be supported, 8378 and capture session creation will fail if it is not. 8379 8380 </details> 8381 <hal_details> 8382 Do not set this property directly 8383 (it is synthetic and will not be available at the HAL layer); 8384 set the android.scaler.availableStreamConfigurations instead. 8385 8386 Not all output formats may be supported in a configuration with 8387 an input stream of a particular format. For more details, see 8388 android.scaler.availableInputOutputFormatsMap. 8389 8390 It is recommended (but not mandatory) to also include half/quarter 8391 of sensor maximum resolution for JPEG formats (regardless of hardware 8392 level). 8393 8394 (The following is a rewording of the above required table): 8395 8396 The HAL must include sensor maximum resolution (defined by 8397 android.sensor.info.activeArraySize). 8398 8399 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 8400 the HAL must include all YUV_420_888 sizes that have JPEG sizes listed 8401 here as output streams. 8402 8403 It must also include each below resolution if it is smaller than or 8404 equal to the sensor maximum resolution (for both YUV_420_888 and JPEG 8405 formats), as output streams: 8406 8407 * 240p (320 x 240) 8408 * 480p (640 x 480) 8409 * 720p (1280 x 720) 8410 * 1080p (1920 x 1080) 8411 8412 Note that for Performance Class 12 or higher primary cameras (first rear/front facing 8413 camera in the camera ID list), camera framework filters out JPEG sizes smaller than 8414 1080p depending on applications' targetSdkLevel. The camera HAL must still support the 8415 smaller JPEG sizes to maintain backward compatibility. 8416 8417 For LIMITED capability devices 8418 (`android.info.supportedHardwareLevel == LIMITED`), 8419 the HAL only has to list up to the maximum video size 8420 supported by the device. 8421 8422 Regardless of hardware level, every output resolution available for 8423 YUV_420_888 must also be available for IMPLEMENTATION_DEFINED. 8424 8425 This supersedes the following fields, which are now deprecated: 8426 8427 * availableFormats 8428 * available[Processed,Raw,Jpeg]Sizes 8429 </hal_details> 8430 </entry> 8431 <entry name="croppingType" type="byte" visibility="public" enum="true" 8432 hwlevel="legacy"> 8433 <enum> 8434 <value>CENTER_ONLY 8435 <notes> 8436 The camera device only supports centered crop regions. 8437 </notes> 8438 </value> 8439 <value>FREEFORM 8440 <notes> 8441 The camera device supports arbitrarily chosen crop regions. 8442 </notes> 8443 </value> 8444 </enum> 8445 <description>The crop type that this camera device supports.</description> 8446 <details> 8447 When passing a non-centered crop region (android.scaler.cropRegion) to a camera 8448 device that only supports CENTER_ONLY cropping, the camera device will move the 8449 crop region to the center of the sensor active array (android.sensor.info.activeArraySize) 8450 and keep the crop region width and height unchanged. The camera device will return the 8451 final used crop region in metadata result android.scaler.cropRegion. 8452 8453 Camera devices that support FREEFORM cropping will support any crop region that 8454 is inside of the active array. The camera device will apply the same crop region and 8455 return the final used crop region in capture result metadata android.scaler.cropRegion. 8456 8457 Starting from API level 30, 8458 8459 * If the camera device supports FREEFORM cropping, in order to do FREEFORM cropping, the 8460 application must set android.control.zoomRatio to 1.0, and use android.scaler.cropRegion 8461 for zoom. 8462 * To do CENTER_ONLY zoom, the application has below 2 options: 8463 1. Set android.control.zoomRatio to 1.0; adjust zoom by android.scaler.cropRegion. 8464 2. Adjust zoom by android.control.zoomRatio; use android.scaler.cropRegion to crop 8465 the field of view vertically (letterboxing) or horizontally (pillarboxing), but not 8466 windowboxing. 8467 * Setting android.control.zoomRatio to values different than 1.0 and 8468 android.scaler.cropRegion to be windowboxing at the same time are not supported. In this 8469 case, the camera framework will override the android.scaler.cropRegion to be the active 8470 array. 8471 8472 LEGACY capability devices will only support CENTER_ONLY cropping. 8473 </details> 8474 <hal_details> 8475 If the HAL supports android.control.zoomRatio, this tag must be set to CENTER_ONLY. 8476 </hal_details> 8477 </entry> 8478 <entry name="availableRecommendedStreamConfigurations" type="int32" visibility="ndk_public" 8479 optional="true" enum="true" container="array" typedef="recommendedStreamConfiguration" 8480 hal_version="3.4"> 8481 <array> 8482 <size>n</size> 8483 <size>5</size> 8484 </array> 8485 <enum> 8486 <value id="0x0">PREVIEW 8487 <notes> 8488 Preview must only include non-stalling processed stream configurations with 8489 output formats like 8490 {@link android.graphics.ImageFormat#YUV_420_888|AIMAGE_FORMAT_YUV_420_888}, 8491 {@link android.graphics.ImageFormat#PRIVATE|AIMAGE_FORMAT_PRIVATE}, etc. 8492 </notes> 8493 </value> 8494 <value id="0x1">RECORD 8495 <notes> 8496 Video record must include stream configurations that match the advertised 8497 supported media profiles {@link android.media.CamcorderProfile} with 8498 IMPLEMENTATION_DEFINED format. 8499 </notes> 8500 </value> 8501 <value id="0x2">VIDEO_SNAPSHOT 8502 <notes> 8503 Video snapshot must include stream configurations at least as big as 8504 the maximum RECORD resolutions and only with 8505 {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG output format}. 8506 Additionally the configurations shouldn't cause preview glitches and also be able to 8507 run at 30 fps. 8508 </notes> 8509 </value> 8510 <value id="0x3">SNAPSHOT 8511 <notes> 8512 Recommended snapshot stream configurations must include at least one with 8513 size close to android.sensor.info.activeArraySize and 8514 {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG output format}. 8515 Taking into account restrictions on aspect ratio, alignment etc. the area of the 8516 maximum suggested size shouldn’t be less than 97% of the sensor array size area. 8517 </notes> 8518 </value> 8519 <value id="0x4">ZSL 8520 <notes> 8521 If supported, recommended input stream configurations must only be advertised with 8522 ZSL along with other processed and/or stalling output formats. 8523 </notes> 8524 </value> 8525 <value id="0x5">RAW 8526 <notes> 8527 If supported, recommended raw stream configurations must only include RAW based 8528 output formats. 8529 </notes> 8530 </value> 8531 <value id="0x6">LOW_LATENCY_SNAPSHOT 8532 <notes> 8533 If supported, the recommended low latency stream configurations must have 8534 end-to-end latency that does not exceed 200 ms. under standard operating conditions 8535 (reasonable light levels, not loaded system) and using template 8536 TEMPLATE_STILL_CAPTURE. This is primarily for listing configurations for the 8537 {@link android.graphics.ImageFormat#JPEG|AIMAGE_FORMAT_JPEG JPEG output format} 8538 however other supported output formats can be added as well. 8539 </notes> 8540 </value> 8541 <value id="0x7">PUBLIC_END 8542 </value> 8543 <value id="0x8" hal_version="3.8">10BIT_OUTPUT 8544 <notes> 8545 If supported, the recommended 10-bit output stream configurations must include 8546 a subset of the advertised {@link android.graphics.ImageFormat#YCBCR_P010} and 8547 {@link android.graphics.ImageFormat#PRIVATE} outputs that are optimized for power 8548 and performance when registered along with a supported 10-bit dynamic range profile. 8549 see android.hardware.camera2.params.OutputConfiguration#setDynamicRangeProfile for 8550 details. 8551 </notes> 8552 </value> 8553 <value id="0x9" hal_version="3.8">PUBLIC_END_3_8 8554 </value> 8555 <value id="0x18">VENDOR_START 8556 <notes> 8557 Vendor defined use cases. These depend on the vendor implementation. 8558 </notes> 8559 </value> 8560 </enum> 8561 <description>Recommended stream configurations for common client use cases. 8562 </description> 8563 <details>Optional subset of the android.scaler.availableStreamConfigurations that contains 8564 similar tuples listed as 8565 (i.e. width, height, format, output/input stream, usecase bit field). 8566 Camera devices will be able to suggest particular stream configurations which are 8567 power and performance efficient for specific use cases. For more information about 8568 retrieving the suggestions see 8569 {@link android.hardware.camera2.CameraCharacteristics#getRecommendedStreamConfigurationMap}. 8570 </details> 8571 <ndk_details> 8572 The data representation is int[5], which maps to 8573 (width, height, format, output/input stream, usecase bit field). The array can be 8574 parsed using the following pseudo code: 8575 8576 struct StreamConfiguration { 8577 int32_t format; 8578 int32_t width; 8579 int32_t height; 8580 int32_t isInput; }; 8581 8582 void getPreferredStreamConfigurations( 8583 int32_t *array, size_t count, int32_t usecaseId, 8584 Vector < StreamConfiguration > * scs) { 8585 const size_t STREAM_CONFIGURATION_SIZE = 5; 8586 const size_t STREAM_WIDTH_OFFSET = 0; 8587 const size_t STREAM_HEIGHT_OFFSET = 1; 8588 const size_t STREAM_FORMAT_OFFSET = 2; 8589 const size_t STREAM_IS_INPUT_OFFSET = 3; 8590 const size_t STREAM_USECASE_BITMAP_OFFSET = 4; 8591 8592 for (size_t i = 0; i < count; i+= STREAM_CONFIGURATION_SIZE) { 8593 int32_t width = array[i + STREAM_WIDTH_OFFSET]; 8594 int32_t height = array[i + STREAM_HEIGHT_OFFSET]; 8595 int32_t format = array[i + STREAM_FORMAT_OFFSET]; 8596 int32_t isInput = array[i + STREAM_IS_INPUT_OFFSET]; 8597 int32_t supportedUsecases = array[i + STREAM_USECASE_BITMAP_OFFSET]; 8598 if (supportedUsecases & (1 << usecaseId)) { 8599 StreamConfiguration sc = {format, width, height, isInput}; 8600 scs->add(sc); 8601 } 8602 } 8603 } 8604 8605 </ndk_details> 8606 <hal_details> 8607 There are some requirements that need to be considered regarding the usecases and the 8608 suggested configurations: 8609 8610 * If android.scaler.availableRecommendedStreamConfigurations is set, then recommended 8611 stream configurations must be present for all mandatory usecases PREVIEW, 8612 SNAPSHOT, RECORD, VIDEO_SNAPSHOT. ZSL and RAW are 8613 required depending on device capabilities see android.request.availableCapabilities. 8614 * Non-existing usecases and non-vendor usecases within the range 8615 (RAW : VENDOR_START] are prohibited as well as stream configurations not 8616 present in the exhaustive android.scaler.availableStreamConfigurations list. 8617 8618 For example, in case the camera device supports only 4K and 1080p and both resolutions are 8619 recommended for the mandatory usecases except preview which can run efficiently only 8620 on 1080p. The array may look like this: 8621 8622 [3840, 2160, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 8623 ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT, 8624 (1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD | 8625 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT | 8626 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT), 8627 8628 1920, 1080, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 8629 ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT, 8630 (1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_PREVIEW | 8631 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD | 8632 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT | 8633 1<< ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT)] 8634 8635 </hal_details> 8636 </entry> 8637 <entry name="availableRecommendedInputOutputFormatsMap" type="int32" visibility="ndk_public" 8638 optional="true" typedef="reprocessFormatsMap" hal_version="3.4"> 8639 <description>Recommended mappings of image formats that are supported by this 8640 camera device for input streams, to their corresponding output formats. 8641 </description> 8642 <details> 8643 This is a recommended subset of the complete list of mappings found in 8644 android.scaler.availableInputOutputFormatsMap. The same requirements apply here as well. 8645 The list however doesn't need to contain all available and supported mappings. Instead of 8646 this developers must list only recommended and efficient entries. 8647 If set, the information will be available in the ZERO_SHUTTER_LAG recommended stream 8648 configuration see 8649 {@link android.hardware.camera2.CameraCharacteristics#getRecommendedStreamConfigurationMap}. 8650 </details> 8651 <hal_details> 8652 For a code sample of the required data encoding please check 8653 android.scaler.availableInputOutputFormatsMap. 8654 </hal_details> 8655 <tag id="REPROC" /> 8656 </entry> 8657 <entry name="mandatoryStreamCombinations" type="int32" visibility="java_public" 8658 synthetic="true" container="array" typedef="mandatoryStreamCombination" hwlevel="limited"> 8659 <array> 8660 <size>n</size> 8661 </array> 8662 <description> 8663 An array of mandatory stream combinations generated according to the camera device 8664 {@link android.hardware.camera2.CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 8665 and {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES}. 8666 This is an app-readable conversion of the mandatory stream combination 8667 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations). 8668 </description> 8669 <details> 8670 The array of 8671 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 8672 generated according to the documented 8673 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations). 8674 based on specific device level and capabilities. 8675 Clients can use the array as a quick reference to find an appropriate camera stream 8676 combination. 8677 As per documentation, the stream combinations with given PREVIEW, RECORD and 8678 MAXIMUM resolutions and anything smaller from the list given by 8679 {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes} are 8680 guaranteed to work. 8681 For a physical camera not independently exposed in 8682 {@link android.hardware.camera2.CameraManager#getCameraIdList}, the mandatory stream 8683 combinations for that physical camera Id are also generated, so that the application can 8684 configure them as physical streams via the logical camera. 8685 The mandatory stream combination array will be {@code null} in case the device is not 8686 backward compatible. 8687 </details> 8688 <hal_details> 8689 Do not set this property directly 8690 (it is synthetic and will not be available at the HAL layer). 8691 </hal_details> 8692 </entry> 8693 <entry name="mandatoryConcurrentStreamCombinations" type="int32" visibility="java_public" 8694 synthetic="true" container="array" typedef="mandatoryStreamCombination"> 8695 <array> 8696 <size>n</size> 8697 </array> 8698 <description> 8699 An array of mandatory concurrent stream combinations. 8700 This is an app-readable conversion of the concurrent mandatory stream combination 8701 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#concurrent-stream-guaranteed-configurations). 8702 </description> 8703 <details> 8704 The array of 8705 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 8706 generated according to the documented 8707 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#concurrent-stream-guaranteed-configurations) 8708 for each device which has its Id present in the set returned by 8709 {@link android.hardware.camera2.CameraManager#getConcurrentCameraIds}. 8710 Clients can use the array as a quick reference to find an appropriate camera stream 8711 combination. 8712 The mandatory stream combination array will be {@code null} in case the device is not a 8713 part of at least one set of combinations returned by 8714 {@link android.hardware.camera2.CameraManager#getConcurrentCameraIds}. 8715 </details> 8716 <hal_details> 8717 Do not set this property directly 8718 (it is synthetic and will not be available at the HAL layer). 8719 </hal_details> 8720 </entry> 8721 <entry name="availableRotateAndCropModes" type="byte" visibility="public" 8722 type_notes="list of enums" container="array" typedef="enumList" 8723 hal_version="3.5"> 8724 <array> 8725 <size>n</size> 8726 </array> 8727 <description> 8728 List of rotate-and-crop modes for android.scaler.rotateAndCrop that are supported by this camera device. 8729 </description> 8730 <range>Any value listed in android.scaler.rotateAndCrop</range> 8731 <details> 8732 This entry lists the valid modes for android.scaler.rotateAndCrop for this camera device. 8733 8734 Starting with API level 30, all devices will list at least `ROTATE_AND_CROP_NONE`. 8735 Devices with support for rotate-and-crop will additionally list at least 8736 `ROTATE_AND_CROP_AUTO` and `ROTATE_AND_CROP_90`. 8737 </details> 8738 </entry> 8739 </static> 8740 <controls> 8741 <entry name="rotateAndCrop" type="byte" visibility="public" enum="true" 8742 hal_version="3.5"> 8743 <enum> 8744 <value>NONE 8745 <notes>No rotate and crop is applied. Processed outputs are in the sensor orientation. 8746 </notes> 8747 </value> 8748 <value>90 8749 <notes>Processed images are rotated by 90 degrees clockwise, and then cropped 8750 to the original aspect ratio.</notes> 8751 </value> 8752 <value>180 8753 <notes>Processed images are rotated by 180 degrees. Since the aspect ratio does not 8754 change, no cropping is performed.</notes> 8755 </value> 8756 <value>270 8757 <notes>Processed images are rotated by 270 degrees clockwise, and then cropped 8758 to the original aspect ratio.</notes> 8759 </value> 8760 <value>AUTO 8761 <notes>The camera API automatically selects the best concrete value for 8762 rotate-and-crop based on the application's support for resizability and the current 8763 multi-window mode. 8764 8765 If the application does not support resizing but the display mode for its main 8766 Activity is not in a typical orientation, the camera API will set `ROTATE_AND_CROP_90` 8767 or some other supported rotation value, depending on device configuration, 8768 to ensure preview and captured images are correctly shown to the user. Otherwise, 8769 `ROTATE_AND_CROP_NONE` will be selected. 8770 8771 When a value other than NONE is selected, several metadata fields will also be parsed 8772 differently to ensure that coordinates are correctly handled for features like drawing 8773 face detection boxes or passing in tap-to-focus coordinates. The camera API will 8774 convert positions in the active array coordinate system to/from the cropped-and-rotated 8775 coordinate system to make the operation transparent for applications. 8776 8777 No coordinate mapping will be done when the application selects a non-AUTO mode. 8778 </notes> 8779 </value> 8780 </enum> 8781 <description>Whether a rotation-and-crop operation is applied to processed 8782 outputs from the camera.</description> 8783 <range>android.scaler.availableRotateAndCropModes</range> 8784 <details> 8785 This control is primarily intended to help camera applications with no support for 8786 multi-window modes to work correctly on devices where multi-window scenarios are 8787 unavoidable, such as foldables or other devices with variable display geometry or more 8788 free-form window placement (such as laptops, which often place portrait-orientation apps 8789 in landscape with pillarboxing). 8790 8791 If supported, the default value is `ROTATE_AND_CROP_AUTO`, which allows the camera API 8792 to enable backwards-compatibility support for applications that do not support resizing 8793 / multi-window modes, when the device is in fact in a multi-window mode (such as inset 8794 portrait on laptops, or on a foldable device in some fold states). In addition, 8795 `ROTATE_AND_CROP_NONE` and `ROTATE_AND_CROP_90` will always be available if this control 8796 is supported by the device. If not supported, devices API level 30 or higher will always 8797 list only `ROTATE_AND_CROP_NONE`. 8798 8799 When `CROP_AUTO` is in use, and the camera API activates backward-compatibility mode, 8800 several metadata fields will also be parsed differently to ensure that coordinates are 8801 correctly handled for features like drawing face detection boxes or passing in 8802 tap-to-focus coordinates. The camera API will convert positions in the active array 8803 coordinate system to/from the cropped-and-rotated coordinate system to make the 8804 operation transparent for applications. The following controls are affected: 8805 8806 * android.control.aeRegions 8807 * android.control.afRegions 8808 * android.control.awbRegions 8809 * android.statistics.faces 8810 8811 Capture results will contain the actual value selected by the API; 8812 `ROTATE_AND_CROP_AUTO` will never be seen in a capture result. 8813 8814 Applications can also select their preferred cropping mode, either to opt out of the 8815 backwards-compatibility treatment, or to use the cropping feature themselves as needed. 8816 In this case, no coordinate translation will be done automatically, and all controls 8817 will continue to use the normal active array coordinates. 8818 8819 Cropping and rotating is done after the application of digital zoom (via either 8820 android.scaler.cropRegion or android.control.zoomRatio), but before each individual 8821 output is further cropped and scaled. It only affects processed outputs such as 8822 YUV, PRIVATE, and JPEG. It has no effect on RAW outputs. 8823 8824 When `CROP_90` or `CROP_270` are selected, there is a significant loss to the field of 8825 view. For example, with a 4:3 aspect ratio output of 1600x1200, `CROP_90` will still 8826 produce 1600x1200 output, but these buffers are cropped from a vertical 3:4 slice at the 8827 center of the 4:3 area, then rotated to be 4:3, and then upscaled to 1600x1200. Only 8828 56.25% of the original FOV is still visible. In general, for an aspect ratio of `w:h`, 8829 the crop and rotate operation leaves `(h/w)^2` of the field of view visible. For 16:9, 8830 this is ~31.6%. 8831 8832 As a visual example, the figure below shows the effect of `ROTATE_AND_CROP_90` on the 8833 outputs for the following parameters: 8834 8835 * Sensor active array: `2000x1500` 8836 * Crop region: top-left: `(500, 375)`, size: `(1000, 750)` (4:3 aspect ratio) 8837 * Output streams: YUV `640x480` and YUV `1280x720` 8838 * `ROTATE_AND_CROP_90` 8839 8840  8841 8842 With these settings, the regions of the active array covered by the output streams are: 8843 8844 * 640x480 stream crop: top-left: `(219, 375)`, size: `(562, 750)` 8845 * 1280x720 stream crop: top-left: `(289, 375)`, size: `(422, 750)` 8846 8847 Since the buffers are rotated, the buffers as seen by the application are: 8848 8849 * 640x480 stream: top-left: `(781, 375)` on active array, size: `(640, 480)`, downscaled 1.17x from sensor pixels 8850 * 1280x720 stream: top-left: `(711, 375)` on active array, size: `(1280, 720)`, upscaled 1.71x from sensor pixels 8851 </details> 8852 <hal_details> 8853 ROTATE_AND_CROP_AUTO will never be sent to the HAL, though it must be set as the default 8854 value in all the capture request templates by the HAL. The camera service will 8855 translate AUTO to a specific rotation value based on the current application's 8856 multi-window state and its support of resizability. 8857 8858 The HAL also does not need to consider coordinate transforms for ROTATE_AND_CROP - all 8859 capture request and result fields should be kept in the active array coordinate frame. 8860 Any translation required to implement ROTATE_AND_CROP_AUTO will be handled by the camera 8861 service. 8862 </hal_details> 8863 </entry> 8864 </controls> 8865 <dynamic> 8866 <clone entry="android.scaler.rotateAndCrop" kind="controls" hal_version="3.5"> 8867 </clone> 8868 </dynamic> 8869 <static> 8870 <entry name="defaultSecureImageSize" type="int32" visibility="public" 8871 type_notes="width/height for the default secure image data size" container="array" 8872 typedef="size" hal_version="3.6"> 8873 <array> 8874 <size>2</size> 8875 </array> 8876 <description> 8877 Default YUV/PRIVATE size to use for requesting secure image buffers. 8878 </description> 8879 <units>Pixels</units> 8880 <details> 8881 This entry lists the default size supported in the secure camera mode. This entry is 8882 optional on devices support the SECURE_IMAGE_DATA capability. This entry will be null 8883 if the camera device does not list SECURE_IMAGE_DATA capability. 8884 8885 When the key is present, only a PRIVATE/YUV output of the specified size is guaranteed 8886 to be supported by the camera HAL in the secure camera mode. Any other format or 8887 resolutions might not be supported. Use 8888 {@link CameraDevice#isSessionConfigurationSupported|ACameraDevice_isSessionConfigurationSupported} 8889 API to query if a secure session configuration is supported if the device supports this 8890 API. 8891 8892 If this key returns null on a device with SECURE_IMAGE_DATA capability, the application 8893 can assume all output sizes listed in the 8894 {@link 8895 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS} 8896 are supported. 8897 </details> 8898 </entry> 8899 <entry name="physicalCameraMultiResolutionStreamConfigurations" type="int32" 8900 visibility="ndk_public" optional="true" enum="true" container="array" 8901 typedef="streamConfiguration" hwlevel="limited" hal_version="3.6"> 8902 <array> 8903 <size>n</size> 8904 <size>4</size> 8905 </array> 8906 <enum> 8907 <value>OUTPUT</value> 8908 <value>INPUT</value> 8909 </enum> 8910 <description>The available multi-resolution stream configurations that this 8911 physical camera device supports 8912 (i.e. format, width, height, output/input stream). 8913 </description> 8914 <details> 8915 This list contains a subset of the parent logical camera's multi-resolution stream 8916 configurations which belong to this physical camera, and it will advertise and will only 8917 advertise the maximum supported resolutions for a particular format. 8918 8919 If this camera device isn't a physical camera device constituting a logical camera, 8920 but a standalone {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 8921 camera, this field represents the multi-resolution input/output stream configurations of 8922 default mode and max resolution modes. The sizes will be the maximum resolution of a 8923 particular format for default mode and max resolution mode. 8924 8925 This field will only be advertised if the device is a physical camera of a 8926 logical multi-camera device or an ultra high resolution sensor camera. For a logical 8927 multi-camera, the camera API will derive the logical camera’s multi-resolution stream 8928 configurations from all physical cameras. For an ultra high resolution sensor camera, this 8929 is used directly as the camera’s multi-resolution stream configurations. 8930 </details> 8931 <hal_details> 8932 If this field contains input stream configurations, and the camera device is a physical 8933 camera (not a standalone ultra-high resolution camera), the 8934 android.logicalMultiCamera.activePhysicalId tag must be set to the physical camera Id in 8935 the physical camera result metadata. This is to make sure during multi-resolution 8936 reprocessing, the camera HAL is notified of which physical camera the reprocessing 8937 request comes from. 8938 </hal_details> 8939 </entry> 8940 <entry name="multiResolutionStreamConfigurationMap" type="int32" visibility="java_public" 8941 synthetic="true" optional="true" typedef="multiResolutionStreamConfigurationMap"> 8942 <description>The multi-resolution stream configurations supported by this logical camera 8943 or ultra high resolution sensor camera device. 8944 </description> 8945 <details> 8946 Multi-resolution streams can be used by a LOGICAL_MULTI_CAMERA or an 8947 ULTRA_HIGH_RESOLUTION_SENSOR camera where the images sent or received can vary in 8948 resolution per frame. This is useful in cases where the camera device's effective full 8949 resolution changes depending on factors such as the current zoom level, lighting 8950 condition, focus distance, or pixel mode. 8951 8952 * For a logical multi-camera implementing optical zoom, at different zoom level, a 8953 different physical camera may be active, resulting in different full-resolution image 8954 sizes. 8955 * For an ultra high resolution camera, depending on whether the camera operates in default 8956 mode, or maximum resolution mode, the output full-size images may be of either binned 8957 resolution or maximum resolution. 8958 8959 To use multi-resolution output streams, the supported formats can be queried by {@link 8960 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputFormats}. 8961 A {@link android.hardware.camera2.MultiResolutionImageReader} can then be created for a 8962 supported format with the MultiResolutionStreamInfo group queried by {@link 8963 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputInfo}. 8964 8965 If a camera device supports multi-resolution output streams for a particular format, for 8966 each of its mandatory stream combinations, the camera device will support using a 8967 MultiResolutionImageReader for the MAXIMUM stream of supported formats. Refer to 8968 [the table](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-additional-guaranteed-combinations-with-multiresolutionoutputs) 8969 for additional details. 8970 8971 To use multi-resolution input streams, the supported formats can be queried by {@link 8972 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getInputFormats}. 8973 A reprocessable CameraCaptureSession can then be created using an {@link 8974 android.hardware.camera2.params.InputConfiguration InputConfiguration} constructed with 8975 the input MultiResolutionStreamInfo group, queried by {@link 8976 android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getInputInfo}. 8977 8978 If a camera device supports multi-resolution {@code YUV} input and multi-resolution 8979 {@code YUV} output, or multi-resolution {@code PRIVATE} input and multi-resolution 8980 {@code PRIVATE} output, {@code JPEG} and {@code YUV} are guaranteed to be supported 8981 multi-resolution output stream formats. Refer to 8982 [the table](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-additional-guaranteed-combinations-with-multiresolutionoutputs) 8983 for details about the additional mandatory stream combinations in this case. 8984 </details> 8985 <hal_details> 8986 Do not set this property directly 8987 (it is synthetic and will not be available at the HAL layer). 8988 </hal_details> 8989 </entry> 8990 <entry name="availableStreamConfigurationsMaximumResolution" type="int32" 8991 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 8992 hal_version="3.6"> 8993 <array> 8994 <size>n</size> 8995 <size>4</size> 8996 </array> 8997 <enum> 8998 <value>OUTPUT</value> 8999 <value>INPUT</value> 9000 </enum> 9001 <description>The available stream configurations that this 9002 camera device supports (i.e. format, width, height, output/input stream) for a 9003 CaptureRequest with android.sensor.pixelMode set to 9004 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9005 </description> 9006 <details> 9007 Analogous to android.scaler.availableStreamConfigurations, for configurations 9008 which are applicable when android.sensor.pixelMode is set to 9009 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9010 9011 Not all output formats may be supported in a configuration with 9012 an input stream of a particular format. For more details, see 9013 android.scaler.availableInputOutputFormatsMapMaximumResolution. 9014 </details> 9015 <hal_details> 9016 Refer to hal_details for android.scaler.availableStreamConfigurations. 9017 </hal_details> 9018 </entry> 9019 <entry name="availableMinFrameDurationsMaximumResolution" type="int64" visibility="ndk_public" 9020 container="array" typedef="streamConfigurationDuration" hal_version="3.6"> 9021 <array> 9022 <size>4</size> 9023 <size>n</size> 9024 </array> 9025 <description>This lists the minimum frame duration for each 9026 format/size combination when the camera device is sent a CaptureRequest with 9027 android.sensor.pixelMode set to 9028 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9029 </description> 9030 <units>(format, width, height, ns) x n</units> 9031 <details> 9032 Analogous to android.scaler.availableMinFrameDurations, for configurations 9033 which are applicable when android.sensor.pixelMode is set to 9034 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9035 9036 When multiple streams are used in a request (if supported, when android.sensor.pixelMode 9037 is set to 9038 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}), the 9039 minimum frame duration will be max(individual stream min durations). 9040 9041 See android.sensor.frameDuration and 9042 android.scaler.availableStallDurationsMaximumResolution for more details about 9043 calculating the max frame rate. 9044 </details> 9045 </entry> 9046 <entry name="availableStallDurationsMaximumResolution" type="int64" visibility="ndk_public" 9047 container="array" typedef="streamConfigurationDuration" hal_version="3.6"> 9048 <array> 9049 <size>4</size> 9050 <size>n</size> 9051 </array> 9052 <description>This lists the maximum stall duration for each 9053 output format/size combination when CaptureRequests are submitted with 9054 android.sensor.pixelMode set to 9055 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 9056 </description> 9057 <units>(format, width, height, ns) x n</units> 9058 <details> 9059 Analogous to android.scaler.availableMinFrameDurations, for configurations 9060 which are applicable when android.sensor.pixelMode is set to 9061 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9062 </details> 9063 <hal_details> 9064 If possible, it is recommended that all non-JPEG formats 9065 (such as RAW16) should not have a stall duration. RAW10, RAW12, RAW_OPAQUE 9066 and IMPLEMENTATION_DEFINED must not have stall durations. 9067 </hal_details> 9068 </entry> 9069 <entry name="streamConfigurationMapMaximumResolution" type="int32" visibility="java_public" 9070 synthetic="true" typedef="streamConfigurationMap"> 9071 <description>The available stream configurations that this 9072 camera device supports when given a CaptureRequest with android.sensor.pixelMode 9073 set to 9074 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}; 9075 also includes the minimum frame durations 9076 and the stall durations for each format/size combination. 9077 </description> 9078 <details> 9079 Analogous to android.scaler.streamConfigurationMap for CaptureRequests where 9080 android.sensor.pixelMode is 9081 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9082 </details> 9083 <hal_details> 9084 Do not set this property directly 9085 (it is synthetic and will not be available at the HAL layer); 9086 set the android.scaler.availableStreamConfigurationsMaximumResolution instead. 9087 9088 Not all output formats may be supported in a configuration with 9089 an input stream of a particular format. For more details, see 9090 android.scaler.availableInputOutputFormatsMapMaximumResolution. 9091 </hal_details> 9092 </entry> 9093 <entry name="availableInputOutputFormatsMapMaximumResolution" type="int32" 9094 visibility="hidden" typedef="reprocessFormatsMap" hal_version="3.6"> 9095 <description>The mapping of image formats that are supported by this 9096 camera device for input streams, to their corresponding output formats, when 9097 android.sensor.pixelMode is set to 9098 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9099 </description> 9100 <details> 9101 Analogous to android.scaler.availableInputOutputFormatsMap for CaptureRequests where 9102 android.sensor.pixelMode is 9103 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9104 </details> 9105 <hal_details> 9106 Refer to hal details for android.scaler.availableInputOutputFormatsMapMaximumResolution. 9107 </hal_details> 9108 <tag id="REPROC" /> 9109 </entry> 9110 <entry name="mandatoryMaximumResolutionStreamCombinations" type="int32" 9111 visibility="java_public" synthetic="true" container="array" 9112 typedef="mandatoryStreamCombination"> 9113 <array> 9114 <size>n</size> 9115 </array> 9116 <description> 9117 An array of mandatory stream combinations which are applicable when 9118 {@link android.hardware.camera2.CaptureRequest} has android.sensor.pixelMode set 9119 to {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 9120 This is an app-readable conversion of the maximum resolution mandatory stream combination 9121 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#additional-guaranteed-combinations-for-ultra-high-resolution-sensors). 9122 </description> 9123 <details> 9124 The array of 9125 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 9126 generated according to the documented 9127 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#additional-guaranteed-combinations-for-ultra-high-resolution-sensors) 9128 for each device which has the 9129 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 9130 capability. 9131 Clients can use the array as a quick reference to find an appropriate camera stream 9132 combination. 9133 The mandatory stream combination array will be {@code null} in case the device is not an 9134 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 9135 device. 9136 </details> 9137 <hal_details> 9138 Do not set this property directly 9139 (it is synthetic and will not be available at the HAL layer). 9140 </hal_details> 9141 </entry> 9142 <entry name="mandatoryTenBitOutputStreamCombinations" type="int32" 9143 visibility="java_public" synthetic="true" container="array" 9144 typedef="mandatoryStreamCombination"> 9145 <array> 9146 <size>n</size> 9147 </array> 9148 <description> 9149 An array of mandatory stream combinations which are applicable when device support the 9150 10-bit output capability 9151 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 9152 This is an app-readable conversion of the 10 bit output mandatory stream combination 9153 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#10-bit-output-additional-guaranteed-configurations). 9154 </description> 9155 <details> 9156 The array of 9157 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 9158 generated according to the documented 9159 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#10-bit-output-additional-guaranteed-configurations) 9160 for each device which has the 9161 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 9162 capability. 9163 Clients can use the array as a quick reference to find an appropriate camera stream 9164 combination. 9165 The mandatory stream combination array will be {@code null} in case the device is not an 9166 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 9167 device. 9168 </details> 9169 <hal_details> 9170 Do not set this property directly 9171 (it is synthetic and will not be available at the HAL layer). 9172 </hal_details> 9173 </entry> 9174 <entry name="mandatoryPreviewStabilizationOutputStreamCombinations" type="int32" 9175 visibility="java_public" synthetic="true" container="array" 9176 typedef="mandatoryStreamCombination"> 9177 <array> 9178 <size>n</size> 9179 </array> 9180 <description> 9181 An array of mandatory stream combinations which are applicable when device lists 9182 {@code PREVIEW_STABILIZATION} in android.control.availableVideoStabilizationModes. 9183 This is an app-readable conversion of the preview stabilization mandatory stream 9184 combination 9185 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#preview-stabilization-guaranteed-stream-configurations). 9186 </description> 9187 <details> 9188 The array of 9189 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 9190 generated according to the documented 9191 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#preview-stabilization-guaranteed-stream-configurations) 9192 for each device which supports {@code PREVIEW_STABILIZATION} 9193 Clients can use the array as a quick reference to find an appropriate camera stream 9194 combination. 9195 The mandatory stream combination array will be {@code null} in case the device does not 9196 list {@code PREVIEW_STABILIZATION} in android.control.availableVideoStabilizationModes. 9197 </details> 9198 <hal_details> 9199 Do not set this property directly 9200 (it is synthetic and will not be available at the HAL layer). 9201 </hal_details> 9202 </entry> 9203 9204 <entry name="multiResolutionStreamSupported" type="byte" visibility="ndk_public" enum="true" 9205 typedef="boolean" hwlevel="limited" hal_version="3.6"> 9206 <enum> 9207 <value>FALSE</value> 9208 <value>TRUE</value> 9209 </enum> 9210 <description>Whether the camera device supports multi-resolution input or output streams 9211 </description> 9212 <details> 9213 A logical multi-camera or an ultra high resolution camera may support multi-resolution 9214 input or output streams. With multi-resolution output streams, the camera device is able 9215 to output different resolution images depending on the current active physical camera or 9216 pixel mode. With multi-resolution input streams, the camera device can reprocess images 9217 of different resolutions from different physical cameras or sensor pixel modes. 9218 9219 When set to TRUE: 9220 9221 * For a logical multi-camera, the camera framework derives 9222 android.scaler.multiResolutionStreamConfigurationMap by combining the 9223 android.scaler.physicalCameraMultiResolutionStreamConfigurations from its physical 9224 cameras. 9225 * For an ultra-high resolution sensor camera, the camera framework directly copies 9226 the value of android.scaler.physicalCameraMultiResolutionStreamConfigurations to 9227 android.scaler.multiResolutionStreamConfigurationMap. 9228 </details> 9229 <hal_details> 9230 For the HAL to claim support for multi-resolution streams: 9231 9232 * The HAL must support the buffer management API by setting 9233 supportedBufferManagementVersion to HIDL_DEVICE_3_5. 9234 * For a logical multi-camera, when combined from all its physical cameras, there must be 9235 at a minimum one input or output stream format with at least two different 9236 physicalCameraMultiResolutionStreamConfigurations entries for that format. 9237 * For an ultra high resolution sensor camera, for each supported multi-resolution format, 9238 the physicalCameraMultiResolutionStreamConfigurations must contain both the largest stream 9239 configuration within the android.scaler.streamConfigurationMap and the largest stream 9240 configuration within the android.scaler.streamConfigurationMapMaximumResolution. 9241 * If the HAL advertises multi-resolution input stream support for a particular format 9242 (namely PRIVATE, or YUV), the logical multi-camera or ultra high resolution sensor camera 9243 must have the corresponding reprocessing capabilities (PRIVATE_REPROCESSING, 9244 or YUV_REPROCESSING respectively). The camera HAL must support reprocessing the 9245 multi-resolution input stream to the output formats specified in the camera's 9246 android.scaler.availableInputOutputFormatsMap. 9247 </hal_details> 9248 </entry> 9249 </static> 9250 <controls> 9251 <entry name="cropRegionSet" type="byte" visibility="fwk_only" 9252 enum="true" typedef="boolean"> 9253 <enum> 9254 <value>FALSE 9255 <notes>Crop region (android.scaler.cropRegion) has not been set by the 9256 camera client. 9257 </notes> 9258 </value> 9259 <value>TRUE 9260 <notes> 9261 Scaler crop regions (android.scaler.cropRegion) has been set by the camera 9262 client. 9263 </notes> 9264 </value> 9265 </enum> 9266 <description> 9267 Framework-only private key which informs camera fwk that the scaler crop region 9268 (android.scaler.cropRegion) has been set by the client and it need 9269 not be corrected when android.sensor.pixelMode is set to MAXIMUM_RESOLUTION. 9270 </description> 9271 <details> 9272 This must be set to TRUE by the camera2 java fwk when the camera client sets 9273 android.scaler.cropRegion. 9274 </details> 9275 </entry> 9276 </controls> 9277 <static> 9278 <entry name="availableStreamUseCases" type="int64" visibility="public" 9279 enum="true" container="array" hal_version="3.8"> 9280 <array> 9281 <size>n</size> 9282 </array> 9283 <enum> 9284 <value optional="true" id="0x0">DEFAULT 9285 <notes> 9286 Default stream use case. 9287 9288 This use case is the same as when the application doesn't set any use case for 9289 the stream. The camera device uses the properties of the output target, such as 9290 format, dataSpace, or surface class type, to optimize the image processing pipeline. 9291 </notes> 9292 </value> 9293 <value optional="true" id="0x1">PREVIEW 9294 <notes> 9295 Live stream shown to the user. 9296 9297 Optimized for performance and usability as a viewfinder, but not necessarily for 9298 image quality. The output is not meant to be persisted as saved images or video. 9299 9300 No stall if android.control.* are set to FAST. There may be stall if 9301 they are set to HIGH_QUALITY. This use case has the same behavior as the 9302 default SurfaceView and SurfaceTexture targets. Additionally, this use case can be 9303 used for in-app image analysis. 9304 </notes> 9305 </value> 9306 <value optional="true" id="0x2">STILL_CAPTURE 9307 <notes> 9308 Still photo capture. 9309 9310 Optimized for high-quality high-resolution capture, and not expected to maintain 9311 preview-like frame rates. 9312 9313 The stream may have stalls regardless of whether android.control.* is HIGH_QUALITY. 9314 This use case has the same behavior as the default JPEG and RAW related formats. 9315 </notes> 9316 </value> 9317 <value optional="true" id="0x3">VIDEO_RECORD 9318 <notes> 9319 Recording video clips. 9320 9321 Optimized for high-quality video capture, including high-quality image stabilization 9322 if supported by the device and enabled by the application. As a result, may produce 9323 output frames with a substantial lag from real time, to allow for highest-quality 9324 stabilization or other processing. As such, such an output is not suitable for drawing 9325 to screen directly, and is expected to be persisted to disk or similar for later 9326 playback or processing. Only streams that set the VIDEO_RECORD use case are guaranteed 9327 to have video stabilization applied when the video stabilization control is set 9328 to ON, as opposed to PREVIEW_STABILIZATION. 9329 9330 This use case has the same behavior as the default MediaRecorder and MediaCodec 9331 targets. 9332 </notes> 9333 </value> 9334 <value optional="true" id="0x4">PREVIEW_VIDEO_STILL 9335 <notes> 9336 One single stream used for combined purposes of preview, video, and still capture. 9337 9338 For such multi-purpose streams, the camera device aims to make the best tradeoff 9339 between the individual use cases. For example, the STILL_CAPTURE use case by itself 9340 may have stalls for achieving best image quality. But if combined with PREVIEW and 9341 VIDEO_RECORD, the camera device needs to trade off the additional image processing 9342 for speed so that preview and video recording aren't slowed down. 9343 9344 Similarly, VIDEO_RECORD may produce frames with a substantial lag, but 9345 PREVIEW_VIDEO_STILL must have minimal output delay. This means that to enable video 9346 stabilization with this use case, the device must support and the app must select the 9347 PREVIEW_STABILIZATION mode for video stabilization. 9348 </notes> 9349 </value> 9350 <value optional="true" id="0x5">VIDEO_CALL 9351 <notes> 9352 Long-running video call optimized for both power efficiency and video quality. 9353 9354 The camera sensor may run in a lower-resolution mode to reduce power consumption 9355 at the cost of some image and digital zoom quality. Unlike VIDEO_RECORD, VIDEO_CALL 9356 outputs are expected to work in dark conditions, so are usually accompanied with 9357 variable frame rate settings to allow sufficient exposure time in low light. 9358 </notes> 9359 </value> 9360 <value optional="true" id="0x6" hal_version="3.9">CROPPED_RAW 9361 <notes> 9362 Cropped RAW stream when the client chooses to crop the field of view. 9363 9364 Certain types of image sensors can run in binned modes in order to improve signal to 9365 noise ratio while capturing frames. However, at certain zoom levels and / or when 9366 other scene conditions are deemed fit, the camera sub-system may choose to un-bin and 9367 remosaic the sensor's output. This results in a RAW frame which is cropped in field 9368 of view and yet has the same number of pixels as full field of view RAW, thereby 9369 improving image detail. 9370 9371 The resultant field of view of the RAW stream will be greater than or equal to 9372 croppable non-RAW streams. The effective crop region for this RAW stream will be 9373 reflected in the CaptureResult key android.scaler.rawCropRegion. 9374 9375 If this stream use case is set on a non-RAW stream, i.e. not one of : 9376 9377 * {@link android.graphics.ImageFormat#RAW_SENSOR|AIMAGE_FORMAT_RAW16 RAW_SENSOR} 9378 * {@link android.graphics.ImageFormat#RAW10|AIMAGE_FORMAT_RAW10 RAW10} 9379 * {@link android.graphics.ImageFormat#RAW12|AIMAGE_FORMAT_RAW12 RAW12} 9380 9381 session configuration is not guaranteed to succeed. 9382 9383 9384 This stream use case may not be supported on some devices. 9385 </notes> 9386 </value> 9387 <value optional="true" visibility="hidden" id="0x10000">VENDOR_START 9388 <notes> 9389 Vendor defined use cases. These depend on the vendor implementation. 9390 </notes> 9391 </value> 9392 </enum> 9393 <description>The stream use cases supported by this camera device.</description> 9394 <details>The stream use case indicates the purpose of a particular camera stream from 9395 the end-user perspective. Some examples of camera use cases are: preview stream for 9396 live viewfinder shown to the user, still capture for generating high quality photo 9397 capture, video record for encoding the camera output for the purpose of future playback, 9398 and video call for live realtime video conferencing. 9399 9400 With this flag, the camera device can optimize the image processing pipeline 9401 parameters, such as tuning, sensor mode, and ISP settings, independent of 9402 the properties of the immediate camera output surface. For example, if the output 9403 surface is a SurfaceTexture, the stream use case flag can be used to indicate whether 9404 the camera frames eventually go to display, video encoder, 9405 still image capture, or all of them combined. 9406 9407 The application sets the use case of a camera stream by calling 9408 {@link android.hardware.camera2.params.OutputConfiguration#setStreamUseCase}. 9409 9410 A camera device with 9411 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE} 9412 capability must support the following stream use cases: 9413 9414 * DEFAULT 9415 * PREVIEW 9416 * STILL_CAPTURE 9417 * VIDEO_RECORD 9418 * PREVIEW_VIDEO_STILL 9419 * VIDEO_CALL 9420 9421 The guaranteed stream combinations related to stream use case for a camera device with 9422 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE} 9423 capability is documented in the camera device 9424 [guideline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#stream-use-case-capability-additional-guaranteed-configurations). 9425 The application is strongly recommended to use one of the guaranteed stream combinations. 9426 If the application creates a session with a stream combination not in the guaranteed 9427 list, or with mixed DEFAULT and non-DEFAULT use cases within the same session, 9428 the camera device may ignore some stream use cases due to hardware constraints 9429 and implementation details. 9430 9431 For stream combinations not covered by the stream use case mandatory lists, such as 9432 reprocessable session, constrained high speed session, or RAW stream combinations, the 9433 application should leave stream use cases within the session as DEFAULT. 9434 </details> 9435 <hal_details> 9436 The camera HAL must support DEFAULT stream use case to handle scenarios where the 9437 application doesn't explicitly set a stream's use case flag, in which case the camera 9438 framework sets it to DEFAULT. 9439 </hal_details> 9440 </entry> 9441 <entry name="mandatoryUseCaseStreamCombinations" type="int32" visibility="java_public" 9442 synthetic="true" container="array" typedef="mandatoryStreamCombination"> 9443 <array> 9444 <size>n</size> 9445 </array> 9446 <description> 9447 An array of mandatory stream combinations with stream use cases. 9448 This is an app-readable conversion of the mandatory stream combination 9449 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#stream-use-case-capability-additional-guaranteed-configurations) 9450 with each stream's use case being set. 9451 </description> 9452 <details> 9453 The array of 9454 {@link android.hardware.camera2.params.MandatoryStreamCombination combinations} is 9455 generated according to the documented 9456 [guildeline](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#stream-use-case-capability-additional-guaranteed-configurations) 9457 for a camera device with 9458 {@link android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE} 9459 capability. 9460 The mandatory stream combination array will be {@code null} in case the device doesn't 9461 have {@link 9462 android.hardware.camera2.CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE} 9463 capability. 9464 </details> 9465 <hal_details> 9466 Do not set this property directly 9467 (it is synthetic and will not be available at the HAL layer). 9468 </hal_details> 9469 </entry> 9470 </static> 9471 <dynamic> 9472 <entry name="rawCropRegion" type="int32" visibility="public" container="array" 9473 typedef="rectangle" hal_version="3.9"> 9474 <array> 9475 <size>4</size> 9476 </array> 9477 <description> 9478 The region of the sensor that corresponds to the RAW read out for this 9479 capture when the stream use case of a RAW stream is set to CROPPED_RAW. 9480 </description> 9481 <units>Pixel coordinates relative to 9482 android.sensor.info.activeArraySize or 9483 android.sensor.info.preCorrectionActiveArraySize depending on distortion correction 9484 capability and mode</units> 9485 <details> 9486 The coordinate system follows that of android.sensor.info.preCorrectionActiveArraySize. 9487 9488 This CaptureResult key will be set when the corresponding CaptureRequest has a RAW target 9489 with stream use case set to 9490 {@link android.hardware.camera2.CameraMetadata#SCALER_AVAILABLE_STREAM_USE_CASES_CROPPED_RAW}, 9491 otherwise it will be {@code null}. 9492 The value of this key specifies the region of the sensor used for the RAW capture and can 9493 be used to calculate the corresponding field of view of RAW streams. 9494 This field of view will always be >= field of view for (processed) non-RAW streams for the 9495 capture. Note: The region specified may not necessarily be centered. 9496 9497 For example: Assume a camera device has a pre correction active array size of 9498 {@code {0, 0, 1500, 2000}}. If the RAW_CROP_REGION is {@code {500, 375, 1500, 1125}}, that 9499 corresponds to a centered crop of 1/4th of the full field of view RAW stream. 9500 9501 The metadata keys which describe properties of RAW frames: 9502 9503 * android.statistics.hotPixelMap 9504 * android.statistics.lensShadingCorrectionMap 9505 * android.lens.distortion 9506 * android.lens.poseTranslation 9507 * android.lens.poseRotation 9508 * android.lens.distortion 9509 * android.lens.intrinsicCalibration 9510 9511 should be interpreted in the effective after raw crop field-of-view coordinate system. 9512 In this coordinate system, 9513 {android.sensor.info.preCorrectionActiveArraySize.left, 9514 android.sensor.info.preCorrectionActiveArraySize.top} corresponds to the 9515 the top left corner of the cropped RAW frame and 9516 {android.sensor.info.preCorrectionActiveArraySize.right, 9517 android.sensor.info.preCorrectionActiveArraySize.bottom} corresponds to 9518 the bottom right corner. Client applications must use the values of the keys 9519 in the CaptureResult metadata if present. 9520 9521 Crop regions android.scaler.cropRegion, AE/AWB/AF regions and face coordinates still 9522 use the android.sensor.info.activeArraySize coordinate system as usual. 9523 </details> 9524 </entry> 9525 </dynamic> 9526 </section> 9527 <section name="sensor"> 9528 <controls> 9529 <entry name="exposureTime" type="int64" visibility="public" hwlevel="full"> 9530 <description>Duration each pixel is exposed to 9531 light.</description> 9532 <units>Nanoseconds</units> 9533 <range>android.sensor.info.exposureTimeRange</range> 9534 <details>If the sensor can't expose this exact duration, it will shorten the 9535 duration exposed to the nearest possible value (rather than expose longer). 9536 The final exposure time used will be available in the output capture result. 9537 9538 This control is only effective if android.control.aeMode or android.control.mode is set to 9539 OFF; otherwise the auto-exposure algorithm will override this value. 9540 </details> 9541 <tag id="V1" /> 9542 </entry> 9543 <entry name="frameDuration" type="int64" visibility="public" hwlevel="full"> 9544 <description>Duration from start of frame readout to 9545 start of next frame readout.</description> 9546 <units>Nanoseconds</units> 9547 <range>See android.sensor.info.maxFrameDuration, {@link 9548 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS}. 9549 The duration is capped to `max(duration, exposureTime + overhead)`.</range> 9550 <details> 9551 The maximum frame rate that can be supported by a camera subsystem is 9552 a function of many factors: 9553 9554 * Requested resolutions of output image streams 9555 * Availability of binning / skipping modes on the imager 9556 * The bandwidth of the imager interface 9557 * The bandwidth of the various ISP processing blocks 9558 9559 Since these factors can vary greatly between different ISPs and 9560 sensors, the camera abstraction tries to represent the bandwidth 9561 restrictions with as simple a model as possible. 9562 9563 The model presented has the following characteristics: 9564 9565 * The image sensor is always configured to output the smallest 9566 resolution possible given the application's requested output stream 9567 sizes. The smallest resolution is defined as being at least as large 9568 as the largest requested output stream size; the camera pipeline must 9569 never digitally upsample sensor data when the crop region covers the 9570 whole sensor. In general, this means that if only small output stream 9571 resolutions are configured, the sensor can provide a higher frame 9572 rate. 9573 * Since any request may use any or all the currently configured 9574 output streams, the sensor and ISP must be configured to support 9575 scaling a single capture to all the streams at the same time. This 9576 means the camera pipeline must be ready to produce the largest 9577 requested output size without any delay. Therefore, the overall 9578 frame rate of a given configured stream set is governed only by the 9579 largest requested stream resolution. 9580 * Using more than one output stream in a request does not affect the 9581 frame duration. 9582 * Certain format-streams may need to do additional background processing 9583 before data is consumed/produced by that stream. These processors 9584 can run concurrently to the rest of the camera pipeline, but 9585 cannot process more than 1 capture at a time. 9586 9587 The necessary information for the application, given the model above, is provided via 9588 {@link 9589 android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS}. 9590 These are used to determine the maximum frame rate / minimum frame duration that is 9591 possible for a given stream configuration. 9592 9593 Specifically, the application can use the following rules to 9594 determine the minimum frame duration it can request from the camera 9595 device: 9596 9597 1. Let the set of currently configured input/output streams be called `S`. 9598 1. Find the minimum frame durations for each stream in `S`, by looking it up in {@link 9599 android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS} 9600 (with its respective size/format). Let this set of frame durations be called `F`. 9601 1. For any given request `R`, the minimum frame duration allowed for `R` is the maximum 9602 out of all values in `F`. Let the streams used in `R` be called `S_r`. 9603 9604 If none of the streams in `S_r` have a stall time (listed in {@link 9605 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration|ACAMERA_SCALER_AVAILABLE_STALL_DURATIONS} 9606 using its respective size/format), then the frame duration in `F` determines the steady 9607 state frame rate that the application will get if it uses `R` as a repeating request. Let 9608 this special kind of request be called `Rsimple`. 9609 9610 A repeating request `Rsimple` can be _occasionally_ interleaved by a single capture of a 9611 new request `Rstall` (which has at least one in-use stream with a non-0 stall time) and if 9612 `Rstall` has the same minimum frame duration this will not cause a frame rate loss if all 9613 buffers from the previous `Rstall` have already been delivered. 9614 9615 For more details about stalling, see {@link 9616 android.hardware.camera2.params.StreamConfigurationMap#getOutputStallDuration|ACAMERA_SCALER_AVAILABLE_STALL_DURATIONS}. 9617 9618 This control is only effective if android.control.aeMode or android.control.mode is set to 9619 OFF; otherwise the auto-exposure algorithm will override this value. 9620 9621 *Note:* Prior to Android 13, this field was described as measuring the duration from 9622 start of frame exposure to start of next frame exposure, which doesn't reflect the 9623 definition from sensor manufacturer. A mobile sensor defines the frame duration as 9624 intervals between sensor readouts. 9625 </details> 9626 <hal_details> 9627 For more details about stalling, see 9628 android.scaler.availableStallDurations. 9629 </hal_details> 9630 <tag id="V1" /> 9631 </entry> 9632 <entry name="sensitivity" type="int32" visibility="public" hwlevel="full"> 9633 <description>The amount of gain applied to sensor data 9634 before processing.</description> 9635 <units>ISO arithmetic units</units> 9636 <range>android.sensor.info.sensitivityRange</range> 9637 <details> 9638 The sensitivity is the standard ISO sensitivity value, 9639 as defined in ISO 12232:2006. 9640 9641 The sensitivity must be within android.sensor.info.sensitivityRange, and 9642 if if it less than android.sensor.maxAnalogSensitivity, the camera device 9643 is guaranteed to use only analog amplification for applying the gain. 9644 9645 If the camera device cannot apply the exact sensitivity 9646 requested, it will reduce the gain to the nearest supported 9647 value. The final sensitivity used will be available in the 9648 output capture result. 9649 9650 This control is only effective if android.control.aeMode or android.control.mode is set to 9651 OFF; otherwise the auto-exposure algorithm will override this value. 9652 9653 Note that for devices supporting postRawSensitivityBoost, the total sensitivity applied 9654 to the final processed image is the combination of android.sensor.sensitivity and 9655 android.control.postRawSensitivityBoost. In case the application uses the sensor 9656 sensitivity from last capture result of an auto request for a manual request, in order 9657 to achieve the same brightness in the output image, the application should also 9658 set postRawSensitivityBoost. 9659 </details> 9660 <hal_details>ISO 12232:2006 REI method is acceptable.</hal_details> 9661 <tag id="V1" /> 9662 </entry> 9663 </controls> 9664 <static> 9665 <namespace name="info"> 9666 <entry name="activeArraySize" type="int32" visibility="public" 9667 type_notes="Four ints defining the active pixel rectangle" 9668 container="array" typedef="rectangle" hwlevel="legacy"> 9669 <array> 9670 <size>4</size> 9671 </array> 9672 <description> 9673 The area of the image sensor which corresponds to active pixels after any geometric 9674 distortion correction has been applied. 9675 </description> 9676 <units>Pixel coordinates on the image sensor</units> 9677 <details> 9678 This is the rectangle representing the size of the active region of the sensor (i.e. 9679 the region that actually receives light from the scene) after any geometric correction 9680 has been applied, and should be treated as the maximum size in pixels of any of the 9681 image output formats aside from the raw formats. 9682 9683 This rectangle is defined relative to the full pixel array; (0,0) is the top-left of 9684 the full pixel array, and the size of the full pixel array is given by 9685 android.sensor.info.pixelArraySize. 9686 9687 The coordinate system for most other keys that list pixel coordinates, including 9688 android.scaler.cropRegion, is defined relative to the active array rectangle given in 9689 this field, with `(0, 0)` being the top-left of this rectangle. 9690 9691 The active array may be smaller than the full pixel array, since the full array may 9692 include black calibration pixels or other inactive regions. 9693 9694 For devices that do not support android.distortionCorrection.mode control, the active 9695 array must be the same as android.sensor.info.preCorrectionActiveArraySize. 9696 9697 For devices that support android.distortionCorrection.mode control, the active array must 9698 be enclosed by android.sensor.info.preCorrectionActiveArraySize. The difference between 9699 pre-correction active array and active array accounts for scaling or cropping caused 9700 by lens geometric distortion correction. 9701 9702 In general, application should always refer to active array size for controls like 9703 metering regions or crop region. Two exceptions are when the application is dealing with 9704 RAW image buffers (RAW_SENSOR, RAW10, RAW12 etc), or when application explicitly set 9705 android.distortionCorrection.mode to OFF. In these cases, application should refer 9706 to android.sensor.info.preCorrectionActiveArraySize. 9707 </details> 9708 <ndk_details> 9709 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 9710 </ndk_details> 9711 <hal_details> 9712 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 9713 &gt;= `(0,0)`. 9714 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySize`. 9715 </hal_details> 9716 <tag id="RAW" /> 9717 </entry> 9718 <entry name="sensitivityRange" type="int32" visibility="public" 9719 type_notes="Range of supported sensitivities" 9720 container="array" typedef="rangeInt" 9721 hwlevel="full"> 9722 <array> 9723 <size>2</size> 9724 </array> 9725 <description>Range of sensitivities for android.sensor.sensitivity supported by this 9726 camera device.</description> 9727 <range>Min <= 100, Max &gt;= 800</range> 9728 <details> 9729 The values are the standard ISO sensitivity values, 9730 as defined in ISO 12232:2006. 9731 </details> 9732 9733 <tag id="BC" /> 9734 <tag id="V1" /> 9735 </entry> 9736 <entry name="colorFilterArrangement" type="byte" visibility="public" enum="true" 9737 hwlevel="full"> 9738 <enum> 9739 <value>RGGB</value> 9740 <value>GRBG</value> 9741 <value>GBRG</value> 9742 <value>BGGR</value> 9743 <value>RGB 9744 <notes>Sensor is not Bayer; output has 3 16-bit 9745 values for each pixel, instead of just 1 16-bit value 9746 per pixel.</notes></value> 9747 <value hal_version="3.4">MONO 9748 <notes>Sensor doesn't have any Bayer color filter. 9749 Such sensor captures visible light in monochrome. The exact weighting and 9750 wavelengths captured is not specified, but generally only includes the visible 9751 frequencies. This value implies a MONOCHROME camera.</notes></value> 9752 <value hal_version="3.4">NIR 9753 <notes>Sensor has a near infrared filter capturing light with wavelength between 9754 roughly 750nm and 1400nm, and the same filter covers the whole sensor array. This 9755 value implies a MONOCHROME camera.</notes></value> 9756 </enum> 9757 <description>The arrangement of color filters on sensor; 9758 represents the colors in the top-left 2x2 section of 9759 the sensor, in reading order, for a Bayer camera, or the 9760 light spectrum it captures for MONOCHROME camera. 9761 </description> 9762 <hal_details> 9763 Starting from Android Q, the colorFilterArrangement for a MONOCHROME camera must be 9764 single color patterns, such as MONO or NIR. 9765 </hal_details> 9766 <tag id="RAW" /> 9767 </entry> 9768 <entry name="exposureTimeRange" type="int64" visibility="public" 9769 type_notes="nanoseconds" container="array" typedef="rangeLong" 9770 hwlevel="full"> 9771 <array> 9772 <size>2</size> 9773 </array> 9774 <description>The range of image exposure times for android.sensor.exposureTime supported 9775 by this camera device. 9776 </description> 9777 <units>Nanoseconds</units> 9778 <range>The minimum exposure time will be less than 100 us. For FULL 9779 capability devices (android.info.supportedHardwareLevel == FULL), 9780 the maximum exposure time will be greater than 100ms.</range> 9781 <hal_details>For FULL capability devices (android.info.supportedHardwareLevel == FULL), 9782 The maximum of the range SHOULD be at least 1 second (1e9), MUST be at least 9783 100ms. 9784 </hal_details> 9785 <tag id="V1" /> 9786 </entry> 9787 <entry name="maxFrameDuration" type="int64" visibility="public" 9788 hwlevel="full"> 9789 <description>The maximum possible frame duration (minimum frame rate) for 9790 android.sensor.frameDuration that is supported this camera device.</description> 9791 <units>Nanoseconds</units> 9792 <range>For FULL capability devices 9793 (android.info.supportedHardwareLevel == FULL), at least 100ms. 9794 </range> 9795 <details>Attempting to use frame durations beyond the maximum will result in the frame 9796 duration being clipped to the maximum. See that control for a full definition of frame 9797 durations. 9798 9799 Refer to {@link 9800 android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration|ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS} 9801 for the minimum frame duration values. 9802 </details> 9803 <hal_details> 9804 For FULL capability devices (android.info.supportedHardwareLevel == FULL), 9805 The maximum of the range SHOULD be at least 9806 1 second (1e9), MUST be at least 100ms (100e6). 9807 9808 android.sensor.info.maxFrameDuration must be greater or 9809 equal to the android.sensor.info.exposureTimeRange max 9810 value (since exposure time overrides frame duration). 9811 9812 Available minimum frame durations for JPEG must be no greater 9813 than that of the YUV_420_888/IMPLEMENTATION_DEFINED 9814 minimum frame durations (for that respective size). 9815 9816 Since JPEG processing is considered offline and can take longer than 9817 a single uncompressed capture, refer to 9818 android.scaler.availableStallDurations 9819 for details about encoding this scenario. 9820 </hal_details> 9821 <tag id="V1" /> 9822 </entry> 9823 <entry name="physicalSize" type="float" visibility="public" 9824 type_notes="width x height" 9825 container="array" typedef="sizeF" hwlevel="legacy"> 9826 <array> 9827 <size>2</size> 9828 </array> 9829 <description>The physical dimensions of the full pixel 9830 array.</description> 9831 <units>Millimeters</units> 9832 <details>This is the physical size of the sensor pixel 9833 array defined by android.sensor.info.pixelArraySize. 9834 </details> 9835 <hal_details>Needed for FOV calculation for old API</hal_details> 9836 <tag id="V1" /> 9837 <tag id="BC" /> 9838 </entry> 9839 <entry name="pixelArraySize" type="int32" visibility="public" 9840 container="array" typedef="size" hwlevel="legacy"> 9841 <array> 9842 <size>2</size> 9843 </array> 9844 <description>Dimensions of the full pixel array, possibly 9845 including black calibration pixels.</description> 9846 <units>Pixels</units> 9847 <details>The pixel count of the full pixel array of the image sensor, which covers 9848 android.sensor.info.physicalSize area. This represents the full pixel dimensions of 9849 the raw buffers produced by this sensor. 9850 9851 If a camera device supports raw sensor formats, either this or 9852 android.sensor.info.preCorrectionActiveArraySize is the maximum dimensions for the raw 9853 output formats listed in {@link 9854 android.hardware.camera2.params.StreamConfigurationMap|ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 9855 (this depends on whether or not the image sensor returns buffers containing pixels that 9856 are not part of the active array region for blacklevel calibration or other purposes). 9857 9858 Some parts of the full pixel array may not receive light from the scene, 9859 or be otherwise inactive. The android.sensor.info.preCorrectionActiveArraySize key 9860 defines the rectangle of active pixels that will be included in processed image 9861 formats. 9862 </details> 9863 <tag id="RAW" /> 9864 <tag id="BC" /> 9865 </entry> 9866 <entry name="whiteLevel" type="int32" visibility="public"> 9867 <description> 9868 Maximum raw value output by sensor. 9869 </description> 9870 <range>&gt; 255 (8-bit output)</range> 9871 <details> 9872 This specifies the fully-saturated encoding level for the raw 9873 sample values from the sensor. This is typically caused by the 9874 sensor becoming highly non-linear or clipping. The minimum for 9875 each channel is specified by the offset in the 9876 android.sensor.blackLevelPattern key. 9877 9878 The white level is typically determined either by sensor bit depth 9879 (8-14 bits is expected), or by the point where the sensor response 9880 becomes too non-linear to be useful. The default value for this is 9881 maximum representable value for a 16-bit raw sample (2^16 - 1). 9882 9883 The white level values of captured images may vary for different 9884 capture settings (e.g., android.sensor.sensitivity). This key 9885 represents a coarse approximation for such case. It is recommended 9886 to use android.sensor.dynamicWhiteLevel for captures when supported 9887 by the camera device, which provides more accurate white level values. 9888 </details> 9889 <hal_details> 9890 The full bit depth of the sensor must be available in the raw data, 9891 so the value for linear sensors should not be significantly lower 9892 than maximum raw value supported, i.e. 2^(sensor bits per pixel). 9893 </hal_details> 9894 <tag id="RAW" /> 9895 </entry> 9896 <entry name="timestampSource" type="byte" visibility="public" 9897 enum="true" hwlevel="legacy"> 9898 <enum> 9899 <value>UNKNOWN 9900 <notes> 9901 Timestamps from android.sensor.timestamp are in nanoseconds and monotonic, but can 9902 not be compared to timestamps from other subsystems (e.g. accelerometer, gyro etc.), 9903 or other instances of the same or different camera devices in the same system with 9904 accuracy. However, the timestamps are roughly in the same timebase as 9905 {@link android.os.SystemClock#uptimeMillis}. The accuracy is sufficient for tasks 9906 like A/V synchronization for video recording, at least, and the timestamps can be 9907 directly used together with timestamps from the audio subsystem for that task. 9908 9909 Timestamps between streams and results for a single camera instance are comparable, 9910 and the timestamps for all buffers and the result metadata generated by a single 9911 capture are identical. 9912 </notes> 9913 </value> 9914 <value>REALTIME 9915 <notes> 9916 Timestamps from android.sensor.timestamp are in the same timebase as 9917 {@link android.os.SystemClock#elapsedRealtimeNanos}, 9918 and they can be compared to other timestamps using that base. 9919 9920 When buffers from a REALTIME device are passed directly to a video encoder from the 9921 camera, automatic compensation is done to account for differing timebases of the 9922 audio and camera subsystems. If the application is receiving buffers and then later 9923 sending them to a video encoder or other application where they are compared with 9924 audio subsystem timestamps or similar, this compensation is not present. In those 9925 cases, applications need to adjust the timestamps themselves. Since {@link 9926 android.os.SystemClock#elapsedRealtimeNanos} and {@link 9927 android.os.SystemClock#uptimeMillis} only diverge while the device is asleep, an 9928 offset between the two sources can be measured once per active session and applied 9929 to timestamps for sufficient accuracy for A/V sync. 9930 </notes> 9931 </value> 9932 </enum> 9933 <description>The time base source for sensor capture start timestamps.</description> 9934 <details> 9935 The timestamps provided for captures are always in nanoseconds and monotonic, but 9936 may not based on a time source that can be compared to other system time sources. 9937 9938 This characteristic defines the source for the timestamps, and therefore whether they 9939 can be compared against other system time sources/timestamps. 9940 </details> 9941 <hal_details> 9942 For camera devices implement UNKNOWN, the camera framework expects that the timestamp 9943 source to be SYSTEM_TIME_MONOTONIC. For camera devices implement REALTIME, the camera 9944 framework expects that the timestamp source to be SYSTEM_TIME_BOOTTIME. See 9945 system/core/include/utils/Timers.h for the definition of SYSTEM_TIME_MONOTONIC and 9946 SYSTEM_TIME_BOOTTIME. Note that HAL must follow above expectation; otherwise video 9947 recording might suffer unexpected behavior. 9948 9949 Also, camera devices which implement REALTIME must pass the ITS sensor fusion test which 9950 tests the alignment between camera timestamps and gyro sensor timestamps. 9951 </hal_details> 9952 <tag id="V1" /> 9953 </entry> 9954 <entry name="lensShadingApplied" type="byte" visibility="public" enum="true" 9955 typedef="boolean"> 9956 <enum> 9957 <value>FALSE</value> 9958 <value>TRUE</value> 9959 </enum> 9960 <description>Whether the RAW images output from this camera device are subject to 9961 lens shading correction.</description> 9962 <details> 9963 If `true`, all images produced by the camera device in the `RAW` image formats will have 9964 at least some lens shading correction already applied to it. If `false`, the images will 9965 not be adjusted for lens shading correction. See android.request.maxNumOutputRaw for a 9966 list of RAW image formats. 9967 9968 When `true`, the `lensShadingCorrectionMap` key may still have values greater than 1.0, 9969 and those will need to be applied to any captured RAW frames for them to match the shading 9970 correction of processed buffers such as `YUV` or `JPEG` images. This may occur, for 9971 example, when some basic fixed lens shading correction is applied by hardware to RAW data, 9972 and additional correction is done dynamically in the camera processing pipeline after 9973 demosaicing. 9974 9975 This key will be `null` for all devices do not report this information. 9976 Devices with RAW capability will always report this information in this key. 9977 </details> 9978 </entry> 9979 <entry name="preCorrectionActiveArraySize" type="int32" visibility="public" 9980 type_notes="Four ints defining the active pixel rectangle" container="array" 9981 typedef="rectangle" hwlevel="legacy"> 9982 <array> 9983 <size>4</size> 9984 </array> 9985 <description> 9986 The area of the image sensor which corresponds to active pixels prior to the 9987 application of any geometric distortion correction. 9988 </description> 9989 <units>Pixel coordinates on the image sensor</units> 9990 <details> 9991 This is the rectangle representing the size of the active region of the sensor (i.e. 9992 the region that actually receives light from the scene) before any geometric correction 9993 has been applied, and should be treated as the active region rectangle for any of the 9994 raw formats. All metadata associated with raw processing (e.g. the lens shading 9995 correction map, and radial distortion fields) treats the top, left of this rectangle as 9996 the origin, (0,0). 9997 9998 The size of this region determines the maximum field of view and the maximum number of 9999 pixels that an image from this sensor can contain, prior to the application of 10000 geometric distortion correction. The effective maximum pixel dimensions of a 10001 post-distortion-corrected image is given by the android.sensor.info.activeArraySize 10002 field, and the effective maximum field of view for a post-distortion-corrected image 10003 can be calculated by applying the geometric distortion correction fields to this 10004 rectangle, and cropping to the rectangle given in android.sensor.info.activeArraySize. 10005 10006 E.g. to calculate position of a pixel, (x,y), in a processed YUV output image with the 10007 dimensions in android.sensor.info.activeArraySize given the position of a pixel, 10008 (x', y'), in the raw pixel array with dimensions given in 10009 android.sensor.info.pixelArraySize: 10010 10011 1. Choose a pixel (x', y') within the active array region of the raw buffer given in 10012 android.sensor.info.preCorrectionActiveArraySize, otherwise this pixel is considered 10013 to be outside of the FOV, and will not be shown in the processed output image. 10014 1. Apply geometric distortion correction to get the post-distortion pixel coordinate, 10015 (x_i, y_i). When applying geometric correction metadata, note that metadata for raw 10016 buffers is defined relative to the top, left of the 10017 android.sensor.info.preCorrectionActiveArraySize rectangle. 10018 1. If the resulting corrected pixel coordinate is within the region given in 10019 android.sensor.info.activeArraySize, then the position of this pixel in the 10020 processed output image buffer is `(x_i - activeArray.left, y_i - activeArray.top)`, 10021 when the top, left coordinate of that buffer is treated as (0, 0). 10022 10023 Thus, for pixel x',y' = (25, 25) on a sensor where android.sensor.info.pixelArraySize 10024 is (100,100), android.sensor.info.preCorrectionActiveArraySize is (10, 10, 100, 100), 10025 android.sensor.info.activeArraySize is (20, 20, 80, 80), and the geometric distortion 10026 correction doesn't change the pixel coordinate, the resulting pixel selected in 10027 pixel coordinates would be x,y = (25, 25) relative to the top,left of the raw buffer 10028 with dimensions given in android.sensor.info.pixelArraySize, and would be (5, 5) 10029 relative to the top,left of post-processed YUV output buffer with dimensions given in 10030 android.sensor.info.activeArraySize. 10031 10032 The currently supported fields that correct for geometric distortion are: 10033 10034 1. android.lens.distortion. 10035 10036 If the camera device doesn't support geometric distortion correction, or all of the 10037 geometric distortion fields are no-ops, this rectangle will be the same as the 10038 post-distortion-corrected rectangle given in android.sensor.info.activeArraySize. 10039 10040 This rectangle is defined relative to the full pixel array; (0,0) is the top-left of 10041 the full pixel array, and the size of the full pixel array is given by 10042 android.sensor.info.pixelArraySize. 10043 10044 The pre-correction active array may be smaller than the full pixel array, since the 10045 full array may include black calibration pixels or other inactive regions. 10046 </details> 10047 <ndk_details> 10048 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 10049 </ndk_details> 10050 <hal_details> 10051 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 10052 &gt;= `(0,0)`. 10053 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySize`. 10054 10055 If omitted by the HAL implementation, the camera framework will assume that this is 10056 the same as the post-correction active array region given in 10057 android.sensor.info.activeArraySize. 10058 </hal_details> 10059 <tag id="RAW" /> 10060 </entry> 10061 <entry name="activeArraySizeMaximumResolution" type="int32" visibility="public" 10062 type_notes="Four ints defining the active pixel rectangle" 10063 container="array" typedef="rectangle" hal_version="3.6"> 10064 <array> 10065 <size>4</size> 10066 </array> 10067 <description> 10068 The area of the image sensor which corresponds to active pixels after any geometric 10069 distortion correction has been applied, when the sensor runs in maximum resolution mode. 10070 </description> 10071 <units>Pixel coordinates on the image sensor</units> 10072 <details> 10073 Analogous to android.sensor.info.activeArraySize, when android.sensor.pixelMode 10074 is set to 10075 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10076 Refer to android.sensor.info.activeArraySize for details, with sensor array related keys 10077 replaced with their 10078 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 10079 counterparts. 10080 This key will only be present for devices which advertise the 10081 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10082 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 10083 lists {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode} 10084 </details> 10085 <ndk_details> 10086 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 10087 </ndk_details> 10088 <hal_details> 10089 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 10090 &gt;= `(0,0)`. 10091 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySizeMaximumResolution`. 10092 </hal_details> 10093 <tag id="RAW" /> 10094 </entry> 10095 <entry name="pixelArraySizeMaximumResolution" type="int32" visibility="public" 10096 container="array" typedef="size" hal_version="3.6"> 10097 <array> 10098 <size>2</size> 10099 </array> 10100 <description>Dimensions of the full pixel array, possibly 10101 including black calibration pixels, when the sensor runs in maximum resolution mode. 10102 Analogous to android.sensor.info.pixelArraySize, when android.sensor.pixelMode is 10103 set to 10104 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10105 </description> 10106 <units>Pixels</units> 10107 <details> 10108 The pixel count of the full pixel array of the image sensor, which covers 10109 android.sensor.info.physicalSize area. This represents the full pixel dimensions of 10110 the raw buffers produced by this sensor, when it runs in maximum resolution mode. That 10111 is, when android.sensor.pixelMode is set to 10112 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10113 This key will only be present for devices which advertise the 10114 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10115 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 10116 lists {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode} 10117 </details> 10118 <tag id="RAW" /> 10119 </entry> 10120 <entry name="preCorrectionActiveArraySizeMaximumResolution" type="int32" 10121 visibility="public" type_notes="Four ints defining the active pixel rectangle" 10122 container="array" typedef="rectangle" hal_version="3.6"> 10123 <array> 10124 <size>4</size> 10125 </array> 10126 <description> 10127 The area of the image sensor which corresponds to active pixels prior to the 10128 application of any geometric distortion correction, when the sensor runs in maximum 10129 resolution mode. This key must be used for crop / metering regions, only when 10130 android.sensor.pixelMode is set to 10131 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10132 </description> 10133 <units>Pixel coordinates on the image sensor</units> 10134 <details> 10135 Analogous to android.sensor.info.preCorrectionActiveArraySize, 10136 when android.sensor.pixelMode is set to 10137 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10138 This key will only be present for devices which advertise the 10139 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10140 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 10141 lists {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode} 10142 </details> 10143 <ndk_details> 10144 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 10145 </ndk_details> 10146 <hal_details> 10147 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 10148 &gt;= `(0,0)`. 10149 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySizeMaximumResolution`. 10150 10151 If omitted by the HAL implementation, the camera framework will assume that this is 10152 the same as the post-correction active array region given in 10153 android.sensor.info.activeArraySizeMaximumResolution. 10154 </hal_details> 10155 <tag id="RAW" /> 10156 </entry> 10157 <entry name="binningFactor" type="int32" visibility="public" 10158 container="array" typedef="size" hal_version="3.6"> 10159 <array> 10160 <size>2</size> 10161 </array> 10162 <description> Dimensions of the group of pixels which are under the same color filter. 10163 This specifies the width and height (pair of integers) of the group of pixels which fall 10164 under the same color filter for ULTRA_HIGH_RESOLUTION sensors. 10165 </description> 10166 <units>Pixels</units> 10167 <details> Sensors can have pixels grouped together under the same color filter in order 10168 to improve various aspects of imaging such as noise reduction, low light 10169 performance etc. These groups can be of various sizes such as 2X2 (quad bayer), 10170 3X3 (nona-bayer). This key specifies the length and width of the pixels grouped under 10171 the same color filter. 10172 In case the device has the 10173 {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10174 capability : 10175 10176 * This key will not be present if REMOSAIC_REPROCESSING is not supported, since RAW 10177 images will have a regular bayer pattern. 10178 10179 In case the device does not have the 10180 {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 10181 capability : 10182 10183 * This key will be present if 10184 {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 10185 lists {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode}, since RAW 10186 images may not necessarily have a regular bayer pattern when 10187 {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode} is set to 10188 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 10189 </details> 10190 </entry> 10191 </namespace> 10192 <entry name="referenceIlluminant1" type="byte" visibility="public" 10193 enum="true" permission_needed="true" > 10194 <enum> 10195 <value id="1">DAYLIGHT</value> 10196 <value id="2">FLUORESCENT</value> 10197 <value id="3">TUNGSTEN 10198 <notes>Incandescent light</notes> 10199 </value> 10200 <value id="4">FLASH</value> 10201 <value id="9">FINE_WEATHER</value> 10202 <value id="10">CLOUDY_WEATHER</value> 10203 <value id="11">SHADE</value> 10204 <value id="12">DAYLIGHT_FLUORESCENT 10205 <notes>D 5700 - 7100K</notes> 10206 </value> 10207 <value id="13">DAY_WHITE_FLUORESCENT 10208 <notes>N 4600 - 5400K</notes> 10209 </value> 10210 <value id="14">COOL_WHITE_FLUORESCENT 10211 <notes>W 3900 - 4500K</notes> 10212 </value> 10213 <value id="15">WHITE_FLUORESCENT 10214 <notes>WW 3200 - 3700K</notes> 10215 </value> 10216 <value id="17">STANDARD_A</value> 10217 <value id="18">STANDARD_B</value> 10218 <value id="19">STANDARD_C</value> 10219 <value id="20">D55</value> 10220 <value id="21">D65</value> 10221 <value id="22">D75</value> 10222 <value id="23">D50</value> 10223 <value id="24">ISO_STUDIO_TUNGSTEN</value> 10224 </enum> 10225 <description> 10226 The standard reference illuminant used as the scene light source when 10227 calculating the android.sensor.colorTransform1, 10228 android.sensor.calibrationTransform1, and 10229 android.sensor.forwardMatrix1 matrices. 10230 </description> 10231 <details> 10232 The values in this key correspond to the values defined for the 10233 EXIF LightSource tag. These illuminants are standard light sources 10234 that are often used calibrating camera devices. 10235 10236 If this key is present, then android.sensor.colorTransform1, 10237 android.sensor.calibrationTransform1, and 10238 android.sensor.forwardMatrix1 will also be present. 10239 10240 Some devices may choose to provide a second set of calibration 10241 information for improved quality, including 10242 android.sensor.referenceIlluminant2 and its corresponding matrices. 10243 10244 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10245 the camera device has RAW capability. 10246 </details> 10247 <hal_details> 10248 The first reference illuminant (android.sensor.referenceIlluminant1) 10249 and corresponding matrices must be present to support the RAW capability 10250 and DNG output. 10251 10252 When producing raw images with a color profile that has only been 10253 calibrated against a single light source, it is valid to omit 10254 android.sensor.referenceIlluminant2 along with the 10255 android.sensor.colorTransform2, android.sensor.calibrationTransform2, 10256 and android.sensor.forwardMatrix2 matrices. 10257 10258 If only android.sensor.referenceIlluminant1 is included, it should be 10259 chosen so that it is representative of typical scene lighting. In 10260 general, D50 or DAYLIGHT will be chosen for this case. 10261 10262 If both android.sensor.referenceIlluminant1 and 10263 android.sensor.referenceIlluminant2 are included, they should be 10264 chosen to represent the typical range of scene lighting conditions. 10265 In general, low color temperature illuminant such as Standard-A will 10266 be chosen for the first reference illuminant and a higher color 10267 temperature illuminant such as D65 will be chosen for the second 10268 reference illuminant. 10269 </hal_details> 10270 <tag id="RAW" /> 10271 </entry> 10272 <entry name="referenceIlluminant2" type="byte" visibility="public" 10273 permission_needed="true" > 10274 <description> 10275 The standard reference illuminant used as the scene light source when 10276 calculating the android.sensor.colorTransform2, 10277 android.sensor.calibrationTransform2, and 10278 android.sensor.forwardMatrix2 matrices. 10279 </description> 10280 <range>Any value listed in android.sensor.referenceIlluminant1</range> 10281 <details> 10282 See android.sensor.referenceIlluminant1 for more details. 10283 10284 If this key is present, then android.sensor.colorTransform2, 10285 android.sensor.calibrationTransform2, and 10286 android.sensor.forwardMatrix2 will also be present. 10287 10288 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10289 the camera device has RAW capability. 10290 </details> 10291 <tag id="RAW" /> 10292 </entry> 10293 <entry name="calibrationTransform1" type="rational" 10294 visibility="public" optional="true" 10295 type_notes="3x3 matrix in row-major-order" container="array" 10296 typedef="colorSpaceTransform" permission_needed="true" > 10297 <array> 10298 <size>3</size> 10299 <size>3</size> 10300 </array> 10301 <description> 10302 A per-device calibration transform matrix that maps from the 10303 reference sensor colorspace to the actual device sensor colorspace. 10304 </description> 10305 <details> 10306 This matrix is used to correct for per-device variations in the 10307 sensor colorspace, and is used for processing raw buffer data. 10308 10309 The matrix is expressed as a 3x3 matrix in row-major-order, and 10310 contains a per-device calibration transform that maps colors 10311 from reference sensor color space (i.e. the "golden module" 10312 colorspace) into this camera device's native sensor color 10313 space under the first reference illuminant 10314 (android.sensor.referenceIlluminant1). 10315 10316 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10317 the camera device has RAW capability. 10318 </details> 10319 <tag id="RAW" /> 10320 </entry> 10321 <entry name="calibrationTransform2" type="rational" 10322 visibility="public" optional="true" 10323 type_notes="3x3 matrix in row-major-order" container="array" 10324 typedef="colorSpaceTransform" permission_needed="true" > 10325 <array> 10326 <size>3</size> 10327 <size>3</size> 10328 </array> 10329 <description> 10330 A per-device calibration transform matrix that maps from the 10331 reference sensor colorspace to the actual device sensor colorspace 10332 (this is the colorspace of the raw buffer data). 10333 </description> 10334 <details> 10335 This matrix is used to correct for per-device variations in the 10336 sensor colorspace, and is used for processing raw buffer data. 10337 10338 The matrix is expressed as a 3x3 matrix in row-major-order, and 10339 contains a per-device calibration transform that maps colors 10340 from reference sensor color space (i.e. the "golden module" 10341 colorspace) into this camera device's native sensor color 10342 space under the second reference illuminant 10343 (android.sensor.referenceIlluminant2). 10344 10345 This matrix will only be present if the second reference 10346 illuminant is present. 10347 10348 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10349 the camera device has RAW capability. 10350 </details> 10351 <tag id="RAW" /> 10352 </entry> 10353 <entry name="colorTransform1" type="rational" 10354 visibility="public" optional="true" 10355 type_notes="3x3 matrix in row-major-order" container="array" 10356 typedef="colorSpaceTransform" permission_needed="true" > 10357 <array> 10358 <size>3</size> 10359 <size>3</size> 10360 </array> 10361 <description> 10362 A matrix that transforms color values from CIE XYZ color space to 10363 reference sensor color space. 10364 </description> 10365 <details> 10366 This matrix is used to convert from the standard CIE XYZ color 10367 space to the reference sensor colorspace, and is used when processing 10368 raw buffer data. 10369 10370 The matrix is expressed as a 3x3 matrix in row-major-order, and 10371 contains a color transform matrix that maps colors from the CIE 10372 XYZ color space to the reference sensor color space (i.e. the 10373 "golden module" colorspace) under the first reference illuminant 10374 (android.sensor.referenceIlluminant1). 10375 10376 The white points chosen in both the reference sensor color space 10377 and the CIE XYZ colorspace when calculating this transform will 10378 match the standard white point for the first reference illuminant 10379 (i.e. no chromatic adaptation will be applied by this transform). 10380 10381 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10382 the camera device has RAW capability. 10383 </details> 10384 <tag id="RAW" /> 10385 </entry> 10386 <entry name="colorTransform2" type="rational" 10387 visibility="public" optional="true" 10388 type_notes="3x3 matrix in row-major-order" container="array" 10389 typedef="colorSpaceTransform" permission_needed="true" > 10390 <array> 10391 <size>3</size> 10392 <size>3</size> 10393 </array> 10394 <description> 10395 A matrix that transforms color values from CIE XYZ color space to 10396 reference sensor color space. 10397 </description> 10398 <details> 10399 This matrix is used to convert from the standard CIE XYZ color 10400 space to the reference sensor colorspace, and is used when processing 10401 raw buffer data. 10402 10403 The matrix is expressed as a 3x3 matrix in row-major-order, and 10404 contains a color transform matrix that maps colors from the CIE 10405 XYZ color space to the reference sensor color space (i.e. the 10406 "golden module" colorspace) under the second reference illuminant 10407 (android.sensor.referenceIlluminant2). 10408 10409 The white points chosen in both the reference sensor color space 10410 and the CIE XYZ colorspace when calculating this transform will 10411 match the standard white point for the second reference illuminant 10412 (i.e. no chromatic adaptation will be applied by this transform). 10413 10414 This matrix will only be present if the second reference 10415 illuminant is present. 10416 10417 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10418 the camera device has RAW capability. 10419 </details> 10420 <tag id="RAW" /> 10421 </entry> 10422 <entry name="forwardMatrix1" type="rational" 10423 visibility="public" optional="true" 10424 type_notes="3x3 matrix in row-major-order" container="array" 10425 typedef="colorSpaceTransform" permission_needed="true" > 10426 <array> 10427 <size>3</size> 10428 <size>3</size> 10429 </array> 10430 <description> 10431 A matrix that transforms white balanced camera colors from the reference 10432 sensor colorspace to the CIE XYZ colorspace with a D50 whitepoint. 10433 </description> 10434 <details> 10435 This matrix is used to convert to the standard CIE XYZ colorspace, and 10436 is used when processing raw buffer data. 10437 10438 This matrix is expressed as a 3x3 matrix in row-major-order, and contains 10439 a color transform matrix that maps white balanced colors from the 10440 reference sensor color space to the CIE XYZ color space with a D50 white 10441 point. 10442 10443 Under the first reference illuminant (android.sensor.referenceIlluminant1) 10444 this matrix is chosen so that the standard white point for this reference 10445 illuminant in the reference sensor colorspace is mapped to D50 in the 10446 CIE XYZ colorspace. 10447 10448 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10449 the camera device has RAW capability. 10450 </details> 10451 <tag id="RAW" /> 10452 </entry> 10453 <entry name="forwardMatrix2" type="rational" 10454 visibility="public" optional="true" 10455 type_notes="3x3 matrix in row-major-order" container="array" 10456 typedef="colorSpaceTransform" permission_needed="true" > 10457 <array> 10458 <size>3</size> 10459 <size>3</size> 10460 </array> 10461 <description> 10462 A matrix that transforms white balanced camera colors from the reference 10463 sensor colorspace to the CIE XYZ colorspace with a D50 whitepoint. 10464 </description> 10465 <details> 10466 This matrix is used to convert to the standard CIE XYZ colorspace, and 10467 is used when processing raw buffer data. 10468 10469 This matrix is expressed as a 3x3 matrix in row-major-order, and contains 10470 a color transform matrix that maps white balanced colors from the 10471 reference sensor color space to the CIE XYZ color space with a D50 white 10472 point. 10473 10474 Under the second reference illuminant (android.sensor.referenceIlluminant2) 10475 this matrix is chosen so that the standard white point for this reference 10476 illuminant in the reference sensor colorspace is mapped to D50 in the 10477 CIE XYZ colorspace. 10478 10479 This matrix will only be present if the second reference 10480 illuminant is present. 10481 10482 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10483 the camera device has RAW capability. 10484 </details> 10485 <tag id="RAW" /> 10486 </entry> 10487 <entry name="baseGainFactor" type="rational" 10488 optional="true"> 10489 <description>Gain factor from electrons to raw units when 10490 ISO=100</description> 10491 <tag id="FUTURE" /> 10492 </entry> 10493 <entry name="blackLevelPattern" type="int32" visibility="public" 10494 optional="true" type_notes="2x2 raw count block" container="array" 10495 typedef="blackLevelPattern"> 10496 <array> 10497 <size>4</size> 10498 </array> 10499 <description> 10500 A fixed black level offset for each of the color filter arrangement 10501 (CFA) mosaic channels. 10502 </description> 10503 <range>&gt;= 0 for each.</range> 10504 <details> 10505 This key specifies the zero light value for each of the CFA mosaic 10506 channels in the camera sensor. The maximal value output by the 10507 sensor is represented by the value in android.sensor.info.whiteLevel. 10508 10509 The values are given in the same order as channels listed for the CFA 10510 layout key (see android.sensor.info.colorFilterArrangement), i.e. the 10511 nth value given corresponds to the black level offset for the nth 10512 color channel listed in the CFA. 10513 10514 The black level values of captured images may vary for different 10515 capture settings (e.g., android.sensor.sensitivity). This key 10516 represents a coarse approximation for such case. It is recommended to 10517 use android.sensor.dynamicBlackLevel or use pixels from 10518 android.sensor.opticalBlackRegions directly for captures when 10519 supported by the camera device, which provides more accurate black 10520 level values. For raw capture in particular, it is recommended to use 10521 pixels from android.sensor.opticalBlackRegions to calculate black 10522 level values for each frame. 10523 10524 For a MONOCHROME camera device, all of the 2x2 channels must have the same values. 10525 </details> 10526 <hal_details> 10527 The values are given in row-column scan order, with the first value 10528 corresponding to the element of the CFA in row=0, column=0. 10529 </hal_details> 10530 <tag id="RAW" /> 10531 </entry> 10532 <entry name="maxAnalogSensitivity" type="int32" visibility="public" 10533 optional="true" hwlevel="full"> 10534 <description>Maximum sensitivity that is implemented 10535 purely through analog gain.</description> 10536 <details>For android.sensor.sensitivity values less than or 10537 equal to this, all applied gain must be analog. For 10538 values above this, the gain applied can be a mix of analog and 10539 digital.</details> 10540 <tag id="V1" /> 10541 <tag id="FULL" /> 10542 </entry> 10543 <entry name="orientation" type="int32" visibility="public" 10544 hwlevel="legacy"> 10545 <description>Clockwise angle through which the output image needs to be rotated to be 10546 upright on the device screen in its native orientation. 10547 </description> 10548 <units>Degrees of clockwise rotation; always a multiple of 10549 90</units> 10550 <range>0, 90, 180, 270</range> 10551 <details> 10552 Also defines the direction of rolling shutter readout, which is from top to bottom in 10553 the sensor's coordinate system. 10554 10555 Starting with Android API level 32, camera clients that query the orientation via 10556 {@link android.hardware.camera2.CameraCharacteristics#get} on foldable devices which 10557 include logical cameras can receive a value that can dynamically change depending on the 10558 device/fold state. 10559 Clients are advised to not cache or store the orientation value of such logical sensors. 10560 In case repeated queries to CameraCharacteristics are not preferred, then clients can 10561 also access the entire mapping from device state to sensor orientation in 10562 {@link android.hardware.camera2.params.DeviceStateSensorOrientationMap}. 10563 Do note that a dynamically changing sensor orientation value in camera characteristics 10564 will not be the best way to establish the orientation per frame. Clients that want to 10565 know the sensor orientation of a particular captured frame should query the 10566 android.logicalMultiCamera.activePhysicalId from the corresponding capture result and 10567 check the respective physical camera orientation. 10568 </details> 10569 <ndk_details> 10570 Native camera clients must query android.info.deviceStateOrientations for the mapping 10571 between device state and camera sensor orientation. Dynamic updates to the sensor 10572 orientation are not supported in this code path. 10573 </ndk_details> 10574 <tag id="BC" /> 10575 </entry> 10576 <entry name="profileHueSatMapDimensions" type="int32" 10577 visibility="system" optional="true" 10578 type_notes="Number of samples for hue, saturation, and value" 10579 container="array"> 10580 <array> 10581 <size>3</size> 10582 </array> 10583 <description> 10584 The number of input samples for each dimension of 10585 android.sensor.profileHueSatMap. 10586 </description> 10587 <range> 10588 Hue &gt;= 1, 10589 Saturation &gt;= 2, 10590 Value &gt;= 1 10591 </range> 10592 <details> 10593 The number of input samples for the hue, saturation, and value 10594 dimension of android.sensor.profileHueSatMap. The order of the 10595 dimensions given is hue, saturation, value; where hue is the 0th 10596 element. 10597 </details> 10598 <tag id="RAW" /> 10599 </entry> 10600 </static> 10601 <dynamic> 10602 <clone entry="android.sensor.exposureTime" kind="controls"> 10603 </clone> 10604 <clone entry="android.sensor.frameDuration" 10605 kind="controls"></clone> 10606 <clone entry="android.sensor.sensitivity" kind="controls"> 10607 </clone> 10608 <entry name="timestamp" type="int64" visibility="public" 10609 hwlevel="legacy"> 10610 <description>Time at start of exposure of first 10611 row of the image sensor active array, in nanoseconds.</description> 10612 <units>Nanoseconds</units> 10613 <range>&gt; 0</range> 10614 <details>The timestamps are also included in all image 10615 buffers produced for the same capture, and will be identical 10616 on all the outputs. 10617 10618 When android.sensor.info.timestampSource `==` UNKNOWN, 10619 the timestamps measure time since an unspecified starting point, 10620 and are monotonically increasing. They can be compared with the 10621 timestamps for other captures from the same camera device, but are 10622 not guaranteed to be comparable to any other time source. 10623 10624 When android.sensor.info.timestampSource `==` REALTIME, the 10625 timestamps measure time in the same timebase as {@link 10626 android.os.SystemClock#elapsedRealtimeNanos}, and they can 10627 be compared to other timestamps from other subsystems that 10628 are using that base. 10629 10630 For reprocessing, the timestamp will match the start of exposure of 10631 the input image, i.e. {@link CaptureResult#SENSOR_TIMESTAMP the 10632 timestamp} in the TotalCaptureResult that was used to create the 10633 reprocess capture request. 10634 </details> 10635 <hal_details> 10636 All timestamps must be in reference to the kernel's 10637 CLOCK_BOOTTIME monotonic clock, which properly accounts for 10638 time spent asleep. This allows for synchronization with 10639 sensors that continue to operate while the system is 10640 otherwise asleep. 10641 10642 If android.sensor.info.timestampSource `==` REALTIME, 10643 The timestamp must be synchronized with the timestamps from other 10644 sensor subsystems that are using the same timebase. 10645 10646 For reprocessing, the input image's start of exposure can be looked up 10647 with android.sensor.timestamp from the metadata included in the 10648 capture request. 10649 </hal_details> 10650 <tag id="BC" /> 10651 </entry> 10652 <entry name="temperature" type="float" 10653 optional="true"> 10654 <description>The temperature of the sensor, sampled at the time 10655 exposure began for this frame. 10656 10657 The thermal diode being queried should be inside the sensor PCB, or 10658 somewhere close to it. 10659 </description> 10660 10661 <units>Celsius</units> 10662 <range>Optional. This value is missing if no temperature is available.</range> 10663 <tag id="FUTURE" /> 10664 </entry> 10665 <entry name="neutralColorPoint" type="rational" visibility="public" 10666 optional="true" container="array"> 10667 <array> 10668 <size>3</size> 10669 </array> 10670 <description> 10671 The estimated camera neutral color in the native sensor colorspace at 10672 the time of capture. 10673 </description> 10674 <details> 10675 This value gives the neutral color point encoded as an RGB value in the 10676 native sensor color space. The neutral color point indicates the 10677 currently estimated white point of the scene illumination. It can be 10678 used to interpolate between the provided color transforms when 10679 processing raw sensor data. 10680 10681 The order of the values is R, G, B; where R is in the lowest index. 10682 10683 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10684 the camera device has RAW capability. 10685 </details> 10686 <tag id="RAW" /> 10687 </entry> 10688 <entry name="noiseProfile" type="double" visibility="public" 10689 optional="true" type_notes="Pairs of noise model coefficients" 10690 container="array" typedef="pairDoubleDouble"> 10691 <array> 10692 <size>2</size> 10693 <size>CFA Channels</size> 10694 </array> 10695 <description> 10696 Noise model coefficients for each CFA mosaic channel. 10697 </description> 10698 <details> 10699 This key contains two noise model coefficients for each CFA channel 10700 corresponding to the sensor amplification (S) and sensor readout 10701 noise (O). These are given as pairs of coefficients for each channel 10702 in the same order as channels listed for the CFA layout key 10703 (see android.sensor.info.colorFilterArrangement). This is 10704 represented as an array of Pair&lt;Double, Double&gt;, where 10705 the first member of the Pair at index n is the S coefficient and the 10706 second member is the O coefficient for the nth color channel in the CFA. 10707 10708 These coefficients are used in a two parameter noise model to describe 10709 the amount of noise present in the image for each CFA channel. The 10710 noise model used here is: 10711 10712 N(x) = sqrt(Sx + O) 10713 10714 Where x represents the recorded signal of a CFA channel normalized to 10715 the range [0, 1], and S and O are the noise model coefficients for 10716 that channel. 10717 10718 A more detailed description of the noise model can be found in the 10719 Adobe DNG specification for the NoiseProfile tag. 10720 10721 For a MONOCHROME camera, there is only one color channel. So the noise model coefficients 10722 will only contain one S and one O. 10723 10724 </details> 10725 <hal_details> 10726 For a CFA layout of RGGB, the list of coefficients would be given as 10727 an array of doubles S0,O0,S1,O1,..., where S0 and O0 are the coefficients 10728 for the red channel, S1 and O1 are the coefficients for the first green 10729 channel, etc. 10730 </hal_details> 10731 <tag id="RAW" /> 10732 </entry> 10733 <entry name="profileHueSatMap" type="float" 10734 visibility="system" optional="true" 10735 type_notes="Mapping for hue, saturation, and value" 10736 container="array"> 10737 <array> 10738 <size>hue_samples</size> 10739 <size>saturation_samples</size> 10740 <size>value_samples</size> 10741 <size>3</size> 10742 </array> 10743 <description> 10744 A mapping containing a hue shift, saturation scale, and value scale 10745 for each pixel. 10746 </description> 10747 <units> 10748 The hue shift is given in degrees; saturation and value scale factors are 10749 unitless and are between 0 and 1 inclusive 10750 </units> 10751 <details> 10752 hue_samples, saturation_samples, and value_samples are given in 10753 android.sensor.profileHueSatMapDimensions. 10754 10755 Each entry of this map contains three floats corresponding to the 10756 hue shift, saturation scale, and value scale, respectively; where the 10757 hue shift has the lowest index. The map entries are stored in the key 10758 in nested loop order, with the value divisions in the outer loop, the 10759 hue divisions in the middle loop, and the saturation divisions in the 10760 inner loop. All zero input saturation entries are required to have a 10761 value scale factor of 1.0. 10762 </details> 10763 <tag id="RAW" /> 10764 </entry> 10765 <entry name="profileToneCurve" type="float" 10766 visibility="system" optional="true" 10767 type_notes="Samples defining a spline for a tone-mapping curve" 10768 container="array"> 10769 <array> 10770 <size>samples</size> 10771 <size>2</size> 10772 </array> 10773 <description> 10774 A list of x,y samples defining a tone-mapping curve for gamma adjustment. 10775 </description> 10776 <range> 10777 Each sample has an input range of `[0, 1]` and an output range of 10778 `[0, 1]`. The first sample is required to be `(0, 0)`, and the last 10779 sample is required to be `(1, 1)`. 10780 </range> 10781 <details> 10782 This key contains a default tone curve that can be applied while 10783 processing the image as a starting point for user adjustments. 10784 The curve is specified as a list of value pairs in linear gamma. 10785 The curve is interpolated using a cubic spline. 10786 </details> 10787 <tag id="RAW" /> 10788 </entry> 10789 <entry name="greenSplit" type="float" visibility="public" optional="true"> 10790 <description> 10791 The worst-case divergence between Bayer green channels. 10792 </description> 10793 <range> 10794 &gt;= 0 10795 </range> 10796 <details> 10797 This value is an estimate of the worst case split between the 10798 Bayer green channels in the red and blue rows in the sensor color 10799 filter array. 10800 10801 The green split is calculated as follows: 10802 10803 1. A 5x5 pixel (or larger) window W within the active sensor array is 10804 chosen. The term 'pixel' here is taken to mean a group of 4 Bayer 10805 mosaic channels (R, Gr, Gb, B). The location and size of the window 10806 chosen is implementation defined, and should be chosen to provide a 10807 green split estimate that is both representative of the entire image 10808 for this camera sensor, and can be calculated quickly. 10809 1. The arithmetic mean of the green channels from the red 10810 rows (mean_Gr) within W is computed. 10811 1. The arithmetic mean of the green channels from the blue 10812 rows (mean_Gb) within W is computed. 10813 1. The maximum ratio R of the two means is computed as follows: 10814 `R = max((mean_Gr + 1)/(mean_Gb + 1), (mean_Gb + 1)/(mean_Gr + 1))` 10815 10816 The ratio R is the green split divergence reported for this property, 10817 which represents how much the green channels differ in the mosaic 10818 pattern. This value is typically used to determine the treatment of 10819 the green mosaic channels when demosaicing. 10820 10821 The green split value can be roughly interpreted as follows: 10822 10823 * R &lt; 1.03 is a negligible split (&lt;3% divergence). 10824 * 1.20 &lt;= R &gt;= 1.03 will require some software 10825 correction to avoid demosaic errors (3-20% divergence). 10826 * R &gt; 1.20 will require strong software correction to produce 10827 a usable image (&gt;20% divergence). 10828 10829 Starting from Android Q, this key will not be present for a MONOCHROME camera, even if 10830 the camera device has RAW capability. 10831 </details> 10832 <hal_details> 10833 The green split given may be a static value based on prior 10834 characterization of the camera sensor using the green split 10835 calculation method given here over a large, representative, sample 10836 set of images. Other methods of calculation that produce equivalent 10837 results, and can be interpreted in the same manner, may be used. 10838 </hal_details> 10839 <tag id="RAW" /> 10840 </entry> 10841 </dynamic> 10842 <controls> 10843 <entry name="testPatternData" type="int32" visibility="public" optional="true" container="array"> 10844 <array> 10845 <size>4</size> 10846 </array> 10847 <description> 10848 A pixel `[R, G_even, G_odd, B]` that supplies the test pattern 10849 when android.sensor.testPatternMode is SOLID_COLOR. 10850 </description> 10851 <details> 10852 Each color channel is treated as an unsigned 32-bit integer. 10853 The camera device then uses the most significant X bits 10854 that correspond to how many bits are in its Bayer raw sensor 10855 output. 10856 10857 For example, a sensor with RAW10 Bayer output would use the 10858 10 most significant bits from each color channel. 10859 </details> 10860 <hal_details> 10861 </hal_details> 10862 </entry> 10863 <entry name="testPatternMode" type="int32" visibility="public" optional="true" 10864 enum="true"> 10865 <enum> 10866 <value>OFF 10867 <notes>No test pattern mode is used, and the camera 10868 device returns captures from the image sensor. 10869 10870 This is the default if the key is not set.</notes> 10871 </value> 10872 <value>SOLID_COLOR 10873 <notes> 10874 Each pixel in `[R, G_even, G_odd, B]` is replaced by its 10875 respective color channel provided in 10876 android.sensor.testPatternData. 10877 10878 For example: 10879 10880 android.sensor.testPatternData = [0, 0xFFFFFFFF, 0xFFFFFFFF, 0] 10881 10882 All green pixels are 100% green. All red/blue pixels are black. 10883 10884 android.sensor.testPatternData = [0xFFFFFFFF, 0, 0xFFFFFFFF, 0] 10885 10886 All red pixels are 100% red. Only the odd green pixels 10887 are 100% green. All blue pixels are 100% black. 10888 </notes> 10889 </value> 10890 <value>COLOR_BARS 10891 <notes> 10892 All pixel data is replaced with an 8-bar color pattern. 10893 10894 The vertical bars (left-to-right) are as follows: 10895 10896 * 100% white 10897 * yellow 10898 * cyan 10899 * green 10900 * magenta 10901 * red 10902 * blue 10903 * black 10904 10905 In general the image would look like the following: 10906 10907 W Y C G M R B K 10908 W Y C G M R B K 10909 W Y C G M R B K 10910 W Y C G M R B K 10911 W Y C G M R B K 10912 . . . . . . . . 10913 . . . . . . . . 10914 . . . . . . . . 10915 10916 (B = Blue, K = Black) 10917 10918 Each bar should take up 1/8 of the sensor pixel array width. 10919 When this is not possible, the bar size should be rounded 10920 down to the nearest integer and the pattern can repeat 10921 on the right side. 10922 10923 Each bar's height must always take up the full sensor 10924 pixel array height. 10925 10926 Each pixel in this test pattern must be set to either 10927 0% intensity or 100% intensity. 10928 </notes> 10929 </value> 10930 <value>COLOR_BARS_FADE_TO_GRAY 10931 <notes> 10932 The test pattern is similar to COLOR_BARS, except that 10933 each bar should start at its specified color at the top, 10934 and fade to gray at the bottom. 10935 10936 Furthermore each bar is further subdivided into a left and 10937 right half. The left half should have a smooth gradient, 10938 and the right half should have a quantized gradient. 10939 10940 In particular, the right half's should consist of blocks of the 10941 same color for 1/16th active sensor pixel array width. 10942 10943 The least significant bits in the quantized gradient should 10944 be copied from the most significant bits of the smooth gradient. 10945 10946 The height of each bar should always be a multiple of 128. 10947 When this is not the case, the pattern should repeat at the bottom 10948 of the image. 10949 </notes> 10950 </value> 10951 <value>PN9 10952 <notes> 10953 All pixel data is replaced by a pseudo-random sequence 10954 generated from a PN9 512-bit sequence (typically implemented 10955 in hardware with a linear feedback shift register). 10956 10957 The generator should be reset at the beginning of each frame, 10958 and thus each subsequent raw frame with this test pattern should 10959 be exactly the same as the last. 10960 </notes> 10961 </value> 10962 <value visibility="test" hal_version="3.6">BLACK 10963 <notes> 10964 All pixel data is replaced by 0% intensity (black) values. 10965 10966 This test pattern is identical to SOLID_COLOR with a value of `[0, 0, 0, 0]` for 10967 android.sensor.testPatternData. It is recommended that devices implement full 10968 SOLID_COLOR support instead, but BLACK can be used to provide minimal support for a 10969 test pattern suitable for privacy use cases. 10970 </notes> 10971 </value> 10972 <value id="256">CUSTOM1 10973 <notes>The first custom test pattern. All custom patterns that are 10974 available only on this camera device are at least this numeric 10975 value. 10976 10977 All of the custom test patterns will be static 10978 (that is the raw image must not vary from frame to frame). 10979 </notes> 10980 </value> 10981 </enum> 10982 <description>When enabled, the sensor sends a test pattern instead of 10983 doing a real exposure from the camera. 10984 </description> 10985 <range>android.sensor.availableTestPatternModes</range> 10986 <details> 10987 When a test pattern is enabled, all manual sensor controls specified 10988 by android.sensor.* will be ignored. All other controls should 10989 work as normal. 10990 10991 For example, if manual flash is enabled, flash firing should still 10992 occur (and that the test pattern remain unmodified, since the flash 10993 would not actually affect it). 10994 10995 Defaults to OFF. 10996 </details> 10997 <hal_details> 10998 All test patterns are specified in the Bayer domain. 10999 11000 The HAL may choose to substitute test patterns from the sensor 11001 with test patterns from on-device memory. In that case, it should be 11002 indistinguishable to the ISP whether the data came from the 11003 sensor interconnect bus (such as CSI2) or memory. 11004 11005 For privacy use cases, if the camera device: 11006 11007 * supports SOLID_COLOR or BLACK test patterns, 11008 * is a logical multi-camera, and 11009 * lists testPatternMode as a physical request key, 11010 11011 Each physical camera must support the same SOLID_COLOR and/or BLACK test patterns 11012 as the logical camera. 11013 </hal_details> 11014 </entry> 11015 </controls> 11016 <dynamic> 11017 <clone entry="android.sensor.testPatternData" kind="controls"> 11018 </clone> 11019 <clone entry="android.sensor.testPatternMode" kind="controls"> 11020 </clone> 11021 </dynamic> 11022 <static> 11023 <entry name="availableTestPatternModes" type="int32" visibility="public" optional="true" 11024 type_notes="list of enums" container="array"> 11025 <array> 11026 <size>n</size> 11027 </array> 11028 <description>List of sensor test pattern modes for android.sensor.testPatternMode 11029 supported by this camera device. 11030 </description> 11031 <range>Any value listed in android.sensor.testPatternMode</range> 11032 <details> 11033 Defaults to OFF, and always includes OFF if defined. 11034 </details> 11035 <hal_details> 11036 All custom modes must be >= CUSTOM1. 11037 </hal_details> 11038 </entry> 11039 </static> 11040 <dynamic> 11041 <entry name="rollingShutterSkew" type="int64" visibility="public" hwlevel="limited"> 11042 <description>Duration between the start of exposure for the first row of the image sensor, 11043 and the start of exposure for one past the last row of the image sensor.</description> 11044 <units>Nanoseconds</units> 11045 <range> &gt;= 0 and &lt; 11046 {@link android.hardware.camera2.params.StreamConfigurationMap#getOutputMinFrameDuration}.</range> 11047 <details> 11048 This is the exposure time skew between the first and `(last+1)` row exposure start times. The 11049 first row and the last row are the first and last rows inside of the 11050 android.sensor.info.activeArraySize. 11051 11052 For typical camera sensors that use rolling shutters, this is also equivalent to the frame 11053 readout time. 11054 11055 If the image sensor is operating in a binned or cropped mode due to the current output 11056 target resolutions, it's possible this skew is reported to be larger than the exposure 11057 time, for example, since it is based on the full array even if a partial array is read 11058 out. Be sure to scale the number to cover the section of the sensor actually being used 11059 for the outputs you care about. So if your output covers N rows of the active array of 11060 height H, scale this value by N/H to get the total skew for that viewport. 11061 11062 *Note:* Prior to Android 11, this field was described as measuring duration from 11063 first to last row of the image sensor, which is not equal to the frame readout time for a 11064 rolling shutter sensor. Implementations generally reported the latter value, so to resolve 11065 the inconsistency, the description has been updated to range from (first, last+1) row 11066 exposure start, instead. 11067 </details> 11068 <hal_details> 11069 The HAL must report `0` if the sensor is using global shutter, where all pixels begin 11070 exposure at the same time. 11071 </hal_details> 11072 <tag id="V1" /> 11073 </entry> 11074 </dynamic> 11075 <static> 11076 <entry name="opticalBlackRegions" type="int32" visibility="public" optional="true" 11077 container="array" typedef="rectangle"> 11078 <array> 11079 <size>4</size> 11080 <size>num_regions</size> 11081 </array> 11082 <description>List of disjoint rectangles indicating the sensor 11083 optically shielded black pixel regions. 11084 </description> 11085 <details> 11086 In most camera sensors, the active array is surrounded by some 11087 optically shielded pixel areas. By blocking light, these pixels 11088 provides a reliable black reference for black level compensation 11089 in active array region. 11090 11091 This key provides a list of disjoint rectangles specifying the 11092 regions of optically shielded (with metal shield) black pixel 11093 regions if the camera device is capable of reading out these black 11094 pixels in the output raw images. In comparison to the fixed black 11095 level values reported by android.sensor.blackLevelPattern, this key 11096 may provide a more accurate way for the application to calculate 11097 black level of each captured raw images. 11098 11099 When this key is reported, the android.sensor.dynamicBlackLevel and 11100 android.sensor.dynamicWhiteLevel will also be reported. 11101 </details> 11102 <ndk_details> 11103 The data representation is `int[4]`, which maps to `(left, top, width, height)`. 11104 </ndk_details> 11105 <hal_details> 11106 This array contains (xmin, ymin, width, height). The (xmin, ymin) 11107 must be &gt;= (0,0) and &lt;= 11108 android.sensor.info.pixelArraySize. The (width, height) must be 11109 &lt;= android.sensor.info.pixelArraySize. Each region must be 11110 outside the region reported by 11111 android.sensor.info.preCorrectionActiveArraySize. 11112 11113 The HAL must report minimal number of disjoint regions for the 11114 optically shielded back pixel regions. For example, if a region can 11115 be covered by one rectangle, the HAL must not split this region into 11116 multiple rectangles. 11117 </hal_details> 11118 </entry> 11119 </static> 11120 <dynamic> 11121 <entry name="dynamicBlackLevel" type="float" visibility="public" 11122 optional="true" type_notes="2x2 raw count block" container="array"> 11123 <array> 11124 <size>4</size> 11125 </array> 11126 <description> 11127 A per-frame dynamic black level offset for each of the color filter 11128 arrangement (CFA) mosaic channels. 11129 </description> 11130 <range>&gt;= 0 for each.</range> 11131 <details> 11132 Camera sensor black levels may vary dramatically for different 11133 capture settings (e.g. android.sensor.sensitivity). The fixed black 11134 level reported by android.sensor.blackLevelPattern may be too 11135 inaccurate to represent the actual value on a per-frame basis. The 11136 camera device internal pipeline relies on reliable black level values 11137 to process the raw images appropriately. To get the best image 11138 quality, the camera device may choose to estimate the per frame black 11139 level values either based on optically shielded black regions 11140 (android.sensor.opticalBlackRegions) or its internal model. 11141 11142 This key reports the camera device estimated per-frame zero light 11143 value for each of the CFA mosaic channels in the camera sensor. The 11144 android.sensor.blackLevelPattern may only represent a coarse 11145 approximation of the actual black level values. This value is the 11146 black level used in camera device internal image processing pipeline 11147 and generally more accurate than the fixed black level values. 11148 However, since they are estimated values by the camera device, they 11149 may not be as accurate as the black level values calculated from the 11150 optical black pixels reported by android.sensor.opticalBlackRegions. 11151 11152 The values are given in the same order as channels listed for the CFA 11153 layout key (see android.sensor.info.colorFilterArrangement), i.e. the 11154 nth value given corresponds to the black level offset for the nth 11155 color channel listed in the CFA. 11156 11157 For a MONOCHROME camera, all of the 2x2 channels must have the same values. 11158 11159 This key will be available if android.sensor.opticalBlackRegions is available or the 11160 camera device advertises this key via {@link 11161 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 11162 </details> 11163 <hal_details> 11164 The values are given in row-column scan order, with the first value 11165 corresponding to the element of the CFA in row=0, column=0. 11166 </hal_details> 11167 <tag id="RAW" /> 11168 </entry> 11169 <entry name="dynamicWhiteLevel" type="int32" visibility="public" 11170 optional="true" > 11171 <description> 11172 Maximum raw value output by sensor for this frame. 11173 </description> 11174 <range> &gt;= 0</range> 11175 <details> 11176 Since the android.sensor.blackLevelPattern may change for different 11177 capture settings (e.g., android.sensor.sensitivity), the white 11178 level will change accordingly. This key is similar to 11179 android.sensor.info.whiteLevel, but specifies the camera device 11180 estimated white level for each frame. 11181 11182 This key will be available if android.sensor.opticalBlackRegions is 11183 available or the camera device advertises this key via 11184 {@link android.hardware.camera2.CameraCharacteristics#getAvailableCaptureRequestKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 11185 </details> 11186 <hal_details> 11187 The full bit depth of the sensor must be available in the raw data, 11188 so the value for linear sensors should not be significantly lower 11189 than maximum raw value supported, i.e. 2^(sensor bits per pixel). 11190 </hal_details> 11191 <tag id="RAW" /> 11192 </entry> 11193 </dynamic> 11194 <static> 11195 <entry name="opaqueRawSize" type="int32" visibility="system" container="array"> 11196 <array> 11197 <size>n</size> 11198 <size>3</size> 11199 </array> 11200 <description>Size in bytes for all the listed opaque RAW buffer sizes</description> 11201 <range>Must be large enough to fit the opaque RAW of corresponding size produced by 11202 the camera</range> 11203 <details> 11204 This configurations are listed as `(width, height, size_in_bytes)` tuples. 11205 This is used for sizing the gralloc buffers for opaque RAW buffers. 11206 All RAW_OPAQUE output stream configuration listed in 11207 android.scaler.availableStreamConfigurations will have a corresponding tuple in 11208 this key. 11209 </details> 11210 <hal_details> 11211 This key is added in legacy HAL3.4. 11212 11213 For legacy HAL3.4 or above: devices advertising RAW_OPAQUE format output must list this 11214 key. For legacy HAL3.3 or earlier devices: if RAW_OPAQUE ouput is advertised, camera 11215 framework will derive this key by assuming each pixel takes two bytes and no padding bytes 11216 between rows. 11217 </hal_details> 11218 </entry> 11219 <entry name="opaqueRawSizeMaximumResolution" type="int32" visibility="system" 11220 container="array" hal_version="3.6"> 11221 <array> 11222 <size>n</size> 11223 <size>3</size> 11224 </array> 11225 <description>Size in bytes for all the listed opaque RAW buffer sizes when 11226 android.sensor.pixelMode is set to 11227 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 11228 </description> 11229 <range>Must be large enough to fit the opaque RAW of corresponding size produced by 11230 the camera</range> 11231 <details> 11232 Refer to android.sensor.opaqueRawSize for details. 11233 </details> 11234 <hal_details> 11235 Refer to android.sensor.opaqueRawSize for details. 11236 </hal_details> 11237 </entry> 11238 </static> 11239 <controls> 11240 <entry name="pixelMode" type="byte" visibility="public" enum="true" 11241 hal_version="3.6"> 11242 <enum> 11243 <value>DEFAULT 11244 <notes> This is the default sensor pixel mode. 11245 </notes> 11246 </value> 11247 <value>MAXIMUM_RESOLUTION 11248 <notes> 11249 In this mode, sensors typically do not bin pixels, as a result can offer larger 11250 image sizes. 11251 </notes> 11252 </value> 11253 </enum> 11254 <description> 11255 Switches sensor pixel mode between maximum resolution mode and default mode. 11256 </description> 11257 <details> 11258 This key controls whether the camera sensor operates in 11259 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 11260 mode or not. By default, all camera devices operate in 11261 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_DEFAULT} mode. 11262 When operating in 11263 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_DEFAULT} mode, sensors 11264 would typically perform pixel binning in order to improve low light 11265 performance, noise reduction etc. However, in 11266 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 11267 mode, sensors typically operate in unbinned mode allowing for a larger image size. 11268 The stream configurations supported in 11269 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 11270 mode are also different from those of 11271 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_DEFAULT} mode. 11272 They can be queried through 11273 {@link android.hardware.camera2.CameraCharacteristics#get} with 11274 {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP_MAXIMUM_RESOLUTION}. 11275 Unless reported by both 11276 {@link android.hardware.camera2.params.StreamConfigurationMap}s, the outputs from 11277 `android.scaler.streamConfigurationMapMaximumResolution` and 11278 `android.scaler.streamConfigurationMap` 11279 must not be mixed in the same CaptureRequest. In other words, these outputs are 11280 exclusive to each other. 11281 This key does not need to be set for reprocess requests. 11282 This key will be be present on devices supporting the 11283 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 11284 capability. It may also be present on devices which do not support the aforementioned 11285 capability. In that case: 11286 11287 * The mandatory stream combinations listed in 11288 android.scaler.mandatoryMaximumResolutionStreamCombinations 11289 would not apply. 11290 11291 * The bayer pattern of {@code RAW} streams when 11292 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION} 11293 is selected will be the one listed in android.sensor.info.binningFactor. 11294 11295 * The following keys will always be present: 11296 11297 * android.scaler.streamConfigurationMapMaximumResolution 11298 * android.sensor.info.activeArraySizeMaximumResolution 11299 * android.sensor.info.pixelArraySizeMaximumResolution 11300 * android.sensor.info.preCorrectionActiveArraySizeMaximumResolution 11301 </details> 11302 </entry> 11303 </controls> 11304 <dynamic> 11305 <clone entry="android.sensor.pixelMode" kind="controls"> 11306 </clone> 11307 <entry name="rawBinningFactorUsed" type="byte" visibility="public" enum="true" 11308 typedef="boolean" hal_version="3.6"> 11309 <enum> 11310 <value>TRUE 11311 <notes> The `RAW` targets in this capture have android.sensor.info.binningFactor as the 11312 bayer pattern. 11313 </notes> 11314 </value> 11315 <value>FALSE 11316 <notes> The `RAW` targets have a regular bayer pattern in this capture. 11317 </notes> 11318 </value> 11319 </enum> 11320 <description> 11321 Whether `RAW` images requested have their bayer pattern as described by 11322 android.sensor.info.binningFactor. 11323 </description> 11324 <details> 11325 This key will only be present in devices advertising the 11326 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 11327 capability which also advertise `REMOSAIC_REPROCESSING` capability. On all other devices 11328 RAW targets will have a regular bayer pattern. 11329 </details> 11330 </entry> 11331 </dynamic> 11332 <static> 11333 <entry name="readoutTimestamp" type="byte" visibility="java_public" 11334 enum="true" hwlevel="legacy" hal_version="3.8"> 11335 <enum> 11336 <value>NOT_SUPPORTED 11337 <notes>This camera device doesn't support readout timestamp and onReadoutStarted 11338 callback. 11339 </notes> 11340 </value> 11341 <value>HARDWARE 11342 <notes>This camera device supports the onReadoutStarted callback as well as outputting 11343 readout timestamps. The readout timestamp is generated by the camera hardware and it 11344 has the same accuracy and timing characteristics of the start-of-exposure time. 11345 </notes> 11346 </value> 11347 </enum> 11348 <description>Whether or not the camera device supports readout timestamp and 11349 {@code onReadoutStarted} callback.</description> 11350 <details> 11351 If this tag is {@code HARDWARE}, the camera device calls 11352 {@link CameraCaptureSession.CaptureCallback#onReadoutStarted} in addition to the 11353 {@link CameraCaptureSession.CaptureCallback#onCaptureStarted} callback for each capture. 11354 The timestamp passed into the callback is the start of camera image readout rather than 11355 the start of the exposure. The timestamp source of 11356 {@link CameraCaptureSession.CaptureCallback#onReadoutStarted} is the same as that of 11357 {@link CameraCaptureSession.CaptureCallback#onCaptureStarted}. 11358 11359 In addition, the application can switch an output surface's timestamp from start of 11360 exposure to start of readout by calling 11361 {@link android.hardware.camera2.params.OutputConfiguration#setReadoutTimestampEnabled}. 11362 11363 The readout timestamp is beneficial for video recording, because the encoder favors 11364 uniform timestamps, and the readout timestamps better reflect the cadence camera sensors 11365 output data. 11366 11367 Note that the camera device produces the start-of-exposure and start-of-readout callbacks 11368 together. As a result, the {@link CameraCaptureSession.CaptureCallback#onReadoutStarted} 11369 is called right after {@link CameraCaptureSession.CaptureCallback#onCaptureStarted}. The 11370 difference in start-of-readout and start-of-exposure is the sensor exposure time, plus 11371 certain constant offset. The offset is usually due to camera sensor level crop, and it is 11372 generally constant over time for the same set of output resolutions and capture settings. 11373 </details> 11374 <hal_details> 11375 This property may be set by HAL layers that implement the AIDL interface. If not set 11376 camera framework will implicitly set it to HARDWARE for all AIDL HALs. Camera framework 11377 will force set this to NOT_SUPPORTED for all HIDL HALs, regerdless of whether the HAL 11378 provided a value or not. 11379 </hal_details> 11380 </entry> 11381 </static> 11382 </section> 11383 <section name="shading"> 11384 <controls> 11385 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 11386 <enum> 11387 <value>OFF 11388 <notes>No lens shading correction is applied.</notes></value> 11389 <value>FAST 11390 <notes>Apply lens shading corrections, without slowing 11391 frame rate relative to sensor raw output</notes></value> 11392 <value>HIGH_QUALITY 11393 <notes>Apply high-quality lens shading correction, at the 11394 cost of possibly reduced frame rate.</notes></value> 11395 </enum> 11396 <description>Quality of lens shading correction applied 11397 to the image data.</description> 11398 <range>android.shading.availableModes</range> 11399 <details> 11400 When set to OFF mode, no lens shading correction will be applied by the 11401 camera device, and an identity lens shading map data will be provided 11402 if `android.statistics.lensShadingMapMode == ON`. For example, for lens 11403 shading map with size of `[ 4, 3 ]`, 11404 the output android.statistics.lensShadingCorrectionMap for this case will be an identity 11405 map shown below: 11406 11407 [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11408 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11409 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11410 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11411 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 11412 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] 11413 11414 When set to other modes, lens shading correction will be applied by the camera 11415 device. Applications can request lens shading map data by setting 11416 android.statistics.lensShadingMapMode to ON, and then the camera device will provide lens 11417 shading map data in android.statistics.lensShadingCorrectionMap; the returned shading map 11418 data will be the one applied by the camera device for this capture request. 11419 11420 The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore 11421 the reliability of the map data may be affected by the AE and AWB algorithms. When AE and 11422 AWB are in AUTO modes(android.control.aeMode `!=` OFF and android.control.awbMode `!=` 11423 OFF), to get best results, it is recommended that the applications wait for the AE and AWB 11424 to be converged before using the returned shading map data. 11425 </details> 11426 </entry> 11427 <entry name="strength" type="byte"> 11428 <description>Control the amount of shading correction 11429 applied to the images</description> 11430 <units>unitless: 1-10; 10 is full shading 11431 compensation</units> 11432 <tag id="FUTURE" /> 11433 </entry> 11434 </controls> 11435 <dynamic> 11436 <clone entry="android.shading.mode" kind="controls"> 11437 </clone> 11438 </dynamic> 11439 <static> 11440 <entry name="availableModes" type="byte" visibility="public" 11441 type_notes="List of enums (android.shading.mode)." container="array" 11442 typedef="enumList" hwlevel="legacy"> 11443 <array> 11444 <size>n</size> 11445 </array> 11446 <description> 11447 List of lens shading modes for android.shading.mode that are supported by this camera device. 11448 </description> 11449 <range>Any value listed in android.shading.mode</range> 11450 <details> 11451 This list contains lens shading modes that can be set for the camera device. 11452 Camera devices that support the MANUAL_POST_PROCESSING capability will always 11453 list OFF and FAST mode. This includes all FULL level devices. 11454 LEGACY devices will always only support FAST mode. 11455 </details> 11456 <hal_details> 11457 HAL must support both FAST and HIGH_QUALITY if lens shading correction control is 11458 available on the camera device, but the underlying implementation can be the same for 11459 both modes. That is, if the highest quality implementation on the camera device does not 11460 slow down capture rate, then FAST and HIGH_QUALITY will generate the same output. 11461 </hal_details> 11462 </entry> 11463 </static> 11464 </section> 11465 <section name="statistics"> 11466 <controls> 11467 <entry name="faceDetectMode" type="byte" visibility="public" enum="true" 11468 hwlevel="legacy"> 11469 <enum> 11470 <value>OFF 11471 <notes>Do not include face detection statistics in capture 11472 results.</notes></value> 11473 <value optional="true">SIMPLE 11474 <notes>Return face rectangle and confidence values only. 11475 </notes></value> 11476 <value optional="true">FULL 11477 <notes>Return all face 11478 metadata. 11479 11480 In this mode, face rectangles, scores, landmarks, and face IDs are all valid. 11481 </notes></value> 11482 </enum> 11483 <description>Operating mode for the face detector 11484 unit.</description> 11485 <range>android.statistics.info.availableFaceDetectModes</range> 11486 <details>Whether face detection is enabled, and whether it 11487 should output just the basic fields or the full set of 11488 fields.</details> 11489 <hal_details> 11490 SIMPLE mode must fill in android.statistics.faceRectangles and 11491 android.statistics.faceScores. 11492 FULL mode must also fill in android.statistics.faceIds, and 11493 android.statistics.faceLandmarks. 11494 </hal_details> 11495 <tag id="BC" /> 11496 </entry> 11497 <entry name="histogramMode" type="byte" enum="true" typedef="boolean"> 11498 <enum> 11499 <value>OFF</value> 11500 <value>ON</value> 11501 </enum> 11502 <description>Operating mode for histogram 11503 generation</description> 11504 <tag id="FUTURE" /> 11505 </entry> 11506 <entry name="sharpnessMapMode" type="byte" enum="true" typedef="boolean"> 11507 <enum> 11508 <value>OFF</value> 11509 <value>ON</value> 11510 </enum> 11511 <description>Operating mode for sharpness map 11512 generation</description> 11513 <tag id="FUTURE" /> 11514 </entry> 11515 <entry name="hotPixelMapMode" type="byte" visibility="public" enum="true" 11516 typedef="boolean"> 11517 <enum> 11518 <value>OFF 11519 <notes>Hot pixel map production is disabled. 11520 </notes></value> 11521 <value>ON 11522 <notes>Hot pixel map production is enabled. 11523 </notes></value> 11524 </enum> 11525 <description> 11526 Operating mode for hot pixel map generation. 11527 </description> 11528 <range>android.statistics.info.availableHotPixelMapModes</range> 11529 <details> 11530 If set to `true`, a hot pixel map is returned in android.statistics.hotPixelMap. 11531 If set to `false`, no hot pixel map will be returned. 11532 </details> 11533 <tag id="V1" /> 11534 <tag id="RAW" /> 11535 </entry> 11536 </controls> 11537 <static> 11538 <namespace name="info"> 11539 <entry name="availableFaceDetectModes" type="byte" 11540 visibility="public" 11541 type_notes="List of enums from android.statistics.faceDetectMode" 11542 container="array" 11543 typedef="enumList" 11544 hwlevel="legacy"> 11545 <array> 11546 <size>n</size> 11547 </array> 11548 <description>List of face detection modes for android.statistics.faceDetectMode that are 11549 supported by this camera device. 11550 </description> 11551 <range>Any value listed in android.statistics.faceDetectMode</range> 11552 <details>OFF is always supported. 11553 </details> 11554 </entry> 11555 <entry name="histogramBucketCount" type="int32"> 11556 <description>Number of histogram buckets 11557 supported</description> 11558 <range>&gt;= 64</range> 11559 <tag id="FUTURE" /> 11560 </entry> 11561 <entry name="maxFaceCount" type="int32" visibility="public" hwlevel="legacy"> 11562 <description>The maximum number of simultaneously detectable 11563 faces.</description> 11564 <range>0 for cameras without available face detection; otherwise: 11565 `>=4` for LIMITED or FULL hwlevel devices or 11566 `>0` for LEGACY devices.</range> 11567 <tag id="BC" /> 11568 </entry> 11569 <entry name="maxHistogramCount" type="int32"> 11570 <description>Maximum value possible for a histogram 11571 bucket</description> 11572 <tag id="FUTURE" /> 11573 </entry> 11574 <entry name="maxSharpnessMapValue" type="int32"> 11575 <description>Maximum value possible for a sharpness map 11576 region.</description> 11577 <tag id="FUTURE" /> 11578 </entry> 11579 <entry name="sharpnessMapSize" type="int32" 11580 type_notes="width x height" container="array" typedef="size"> 11581 <array> 11582 <size>2</size> 11583 </array> 11584 <description>Dimensions of the sharpness 11585 map</description> 11586 <range>Must be at least 32 x 32</range> 11587 <tag id="FUTURE" /> 11588 </entry> 11589 <entry name="availableHotPixelMapModes" type="byte" visibility="public" 11590 type_notes="list of enums" container="array" typedef="boolean"> 11591 <array> 11592 <size>n</size> 11593 </array> 11594 <description> 11595 List of hot pixel map output modes for android.statistics.hotPixelMapMode that are 11596 supported by this camera device. 11597 </description> 11598 <range>Any value listed in android.statistics.hotPixelMapMode</range> 11599 <details> 11600 If no hotpixel map output is available for this camera device, this will contain only 11601 `false`. 11602 11603 ON is always supported on devices with the RAW capability. 11604 </details> 11605 <tag id="V1" /> 11606 <tag id="RAW" /> 11607 </entry> 11608 <entry name="availableLensShadingMapModes" type="byte" visibility="public" 11609 type_notes="list of enums" container="array" typedef="enumList"> 11610 <array> 11611 <size>n</size> 11612 </array> 11613 <description> 11614 List of lens shading map output modes for android.statistics.lensShadingMapMode that 11615 are supported by this camera device. 11616 </description> 11617 <range>Any value listed in android.statistics.lensShadingMapMode</range> 11618 <details> 11619 If no lens shading map output is available for this camera device, this key will 11620 contain only OFF. 11621 11622 ON is always supported on devices with the RAW capability. 11623 LEGACY mode devices will always only support OFF. 11624 </details> 11625 </entry> 11626 <entry name="availableOisDataModes" type="byte" visibility="public" 11627 type_notes="list of enums" container="array" typedef="enumList" hal_version="3.3"> 11628 <array> 11629 <size>n</size> 11630 </array> 11631 <description> 11632 List of OIS data output modes for android.statistics.oisDataMode that 11633 are supported by this camera device. 11634 </description> 11635 <range>Any value listed in android.statistics.oisDataMode</range> 11636 <details> 11637 If no OIS data output is available for this camera device, this key will 11638 contain only OFF. 11639 </details> 11640 </entry> 11641 </namespace> 11642 </static> 11643 <dynamic> 11644 <clone entry="android.statistics.faceDetectMode" 11645 kind="controls"></clone> 11646 <entry name="faceIds" type="int32" visibility="ndk_public" 11647 container="array" hwlevel="legacy"> 11648 <array> 11649 <size>n</size> 11650 </array> 11651 <description>List of unique IDs for detected faces.</description> 11652 <details> 11653 Each detected face is given a unique ID that is valid for as long as the face is visible 11654 to the camera device. A face that leaves the field of view and later returns may be 11655 assigned a new ID. 11656 11657 Only available if android.statistics.faceDetectMode == FULL</details> 11658 <tag id="BC" /> 11659 </entry> 11660 <entry name="faceLandmarks" type="int32" visibility="ndk_public" 11661 type_notes="(leftEyeX, leftEyeY, rightEyeX, rightEyeY, mouthX, mouthY)" 11662 container="array" hwlevel="legacy"> 11663 <array> 11664 <size>n</size> 11665 <size>6</size> 11666 </array> 11667 <description>List of landmarks for detected 11668 faces.</description> 11669 <details> 11670 For devices not supporting android.distortionCorrection.mode control, the coordinate 11671 system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being 11672 the top-left pixel of the active array. 11673 11674 For devices supporting android.distortionCorrection.mode control, the coordinate 11675 system depends on the mode being set. 11676 When the distortion correction mode is OFF, the coordinate system follows 11677 android.sensor.info.preCorrectionActiveArraySize, with 11678 `(0, 0)` being the top-left pixel of the pre-correction active array. 11679 When the distortion correction mode is not OFF, the coordinate system follows 11680 android.sensor.info.activeArraySize, with 11681 `(0, 0)` being the top-left pixel of the active array. 11682 11683 Only available if android.statistics.faceDetectMode == FULL. 11684 11685 Starting from API level 30, the coordinate system of activeArraySize or 11686 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 11687 pre-zoomRatio field of view. This means that if the relative position of faces and 11688 the camera device doesn't change, when zooming in by increasing 11689 android.control.zoomRatio, the face landmarks move farther away from the center of the 11690 activeArray or preCorrectionActiveArray. If android.control.zoomRatio is set to 1.0 11691 (default), the face landmarks coordinates won't change as android.scaler.cropRegion 11692 changes. See android.control.zoomRatio for details. Whether to use activeArraySize or 11693 preCorrectionActiveArraySize still depends on distortion correction mode. 11694 </details> 11695 <hal_details> 11696 HAL must always report face landmarks in the coordinate system of pre-correction 11697 active array. 11698 </hal_details> 11699 <tag id="BC" /> 11700 </entry> 11701 <entry name="faceRectangles" type="int32" visibility="ndk_public" 11702 type_notes="(xmin, ymin, xmax, ymax). (0,0) is top-left of active pixel area" 11703 container="array" typedef="rectangle" hwlevel="legacy"> 11704 <array> 11705 <size>n</size> 11706 <size>4</size> 11707 </array> 11708 <description>List of the bounding rectangles for detected 11709 faces.</description> 11710 <details> 11711 For devices not supporting android.distortionCorrection.mode control, the coordinate 11712 system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being 11713 the top-left pixel of the active array. 11714 11715 For devices supporting android.distortionCorrection.mode control, the coordinate 11716 system depends on the mode being set. 11717 When the distortion correction mode is OFF, the coordinate system follows 11718 android.sensor.info.preCorrectionActiveArraySize, with 11719 `(0, 0)` being the top-left pixel of the pre-correction active array. 11720 When the distortion correction mode is not OFF, the coordinate system follows 11721 android.sensor.info.activeArraySize, with 11722 `(0, 0)` being the top-left pixel of the active array. 11723 11724 Only available if android.statistics.faceDetectMode != OFF. 11725 11726 Starting from API level 30, the coordinate system of activeArraySize or 11727 preCorrectionActiveArraySize is used to represent post-zoomRatio field of view, not 11728 pre-zoomRatio field of view. This means that if the relative position of faces and 11729 the camera device doesn't change, when zooming in by increasing 11730 android.control.zoomRatio, the face rectangles grow larger and move farther away from 11731 the center of the activeArray or preCorrectionActiveArray. If android.control.zoomRatio 11732 is set to 1.0 (default), the face rectangles won't change as android.scaler.cropRegion 11733 changes. See android.control.zoomRatio for details. Whether to use activeArraySize or 11734 preCorrectionActiveArraySize still depends on distortion correction mode. 11735 </details> 11736 <ndk_details> 11737 The data representation is `int[4]`, which maps to `(left, top, right, bottom)`. 11738 </ndk_details> 11739 <hal_details> 11740 HAL must always report face rectangles in the coordinate system of pre-correction 11741 active array. 11742 </hal_details> 11743 <tag id="BC" /> 11744 </entry> 11745 <entry name="faceScores" type="byte" visibility="ndk_public" 11746 container="array" hwlevel="legacy"> 11747 <array> 11748 <size>n</size> 11749 </array> 11750 <description>List of the face confidence scores for 11751 detected faces</description> 11752 <range>1-100</range> 11753 <details>Only available if android.statistics.faceDetectMode != OFF. 11754 </details> 11755 <hal_details> 11756 The value should be meaningful (for example, setting 100 at 11757 all times is illegal).</hal_details> 11758 <tag id="BC" /> 11759 </entry> 11760 <entry name="faces" type="int32" visibility="java_public" synthetic="true" 11761 container="array" typedef="face" hwlevel="legacy"> 11762 <array> 11763 <size>n</size> 11764 </array> 11765 <description>List of the faces detected through camera face detection 11766 in this capture.</description> 11767 <details> 11768 Only available if android.statistics.faceDetectMode `!=` OFF. 11769 </details> 11770 </entry> 11771 <entry name="histogram" type="int32" 11772 type_notes="count of pixels for each color channel that fall into each histogram bucket, scaled to be between 0 and maxHistogramCount" 11773 container="array"> 11774 <array> 11775 <size>n</size> 11776 <size>3</size> 11777 </array> 11778 <description>A 3-channel histogram based on the raw 11779 sensor data</description> 11780 <details>The k'th bucket (0-based) covers the input range 11781 (with w = android.sensor.info.whiteLevel) of [ k * w/N, 11782 (k + 1) * w / N ). If only a monochrome sharpness map is 11783 supported, all channels should have the same data</details> 11784 <tag id="FUTURE" /> 11785 </entry> 11786 <clone entry="android.statistics.histogramMode" 11787 kind="controls"></clone> 11788 <entry name="sharpnessMap" type="int32" 11789 type_notes="estimated sharpness for each region of the input image. Normalized to be between 0 and maxSharpnessMapValue. Higher values mean sharper (better focused)" 11790 container="array"> 11791 <array> 11792 <size>n</size> 11793 <size>m</size> 11794 <size>3</size> 11795 </array> 11796 <description>A 3-channel sharpness map, based on the raw 11797 sensor data</description> 11798 <details>If only a monochrome sharpness map is supported, 11799 all channels should have the same data</details> 11800 <tag id="FUTURE" /> 11801 </entry> 11802 <clone entry="android.statistics.sharpnessMapMode" 11803 kind="controls"></clone> 11804 <entry name="lensShadingCorrectionMap" type="byte" visibility="java_public" 11805 typedef="lensShadingMap" hwlevel="full"> 11806 <description>The shading map is a low-resolution floating-point map 11807 that lists the coefficients used to correct for vignetting, for each 11808 Bayer color channel.</description> 11809 <range>Each gain factor is &gt;= 1</range> 11810 <details> 11811 The map provided here is the same map that is used by the camera device to 11812 correct both color shading and vignetting for output non-RAW images. 11813 11814 When there is no lens shading correction applied to RAW 11815 output images (android.sensor.info.lensShadingApplied `==` 11816 false), this map is the complete lens shading correction 11817 map; when there is some lens shading correction applied to 11818 the RAW output image (android.sensor.info.lensShadingApplied 11819 `==` true), this map reports the remaining lens shading 11820 correction map that needs to be applied to get shading 11821 corrected images that match the camera device's output for 11822 non-RAW formats. 11823 11824 Therefore, whatever the value of lensShadingApplied is, the lens 11825 shading map should always be applied to RAW images if the goal is to 11826 match the shading appearance of processed (non-RAW) images. 11827 11828 For a complete shading correction map, the least shaded 11829 section of the image will have a gain factor of 1; all 11830 other sections will have gains above 1. 11831 11832 When android.colorCorrection.mode = TRANSFORM_MATRIX, the map 11833 will take into account the colorCorrection settings. 11834 11835 The shading map is for the entire active pixel array, and is not 11836 affected by the crop region specified in the request. Each shading map 11837 entry is the value of the shading compensation map over a specific 11838 pixel on the sensor. Specifically, with a (N x M) resolution shading 11839 map, and an active pixel array size (W x H), shading map entry 11840 (x,y) ϵ (0 ... N-1, 0 ... M-1) is the value of the shading map at 11841 pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels. 11842 The map is assumed to be bilinearly interpolated between the sample points. 11843 11844 The channel order is [R, Geven, Godd, B], where Geven is the green 11845 channel for the even rows of a Bayer pattern, and Godd is the odd rows. 11846 The shading map is stored in a fully interleaved format. 11847 11848 The shading map will generally have on the order of 30-40 rows and columns, 11849 and will be smaller than 64x64. 11850 11851 As an example, given a very small map defined as: 11852 11853 width,height = [ 4, 3 ] 11854 values = 11855 [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2, 11856 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3, 11857 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0, 11858 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2, 11859 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2, 11860 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ] 11861 11862 The low-resolution scaling map images for each channel are 11863 (displayed using nearest-neighbor interpolation): 11864 11865  11866  11867  11868  11869 11870 As a visualization only, inverting the full-color map to recover an 11871 image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives: 11872 11873  11874 11875 For a MONOCHROME camera, all of the 2x2 channels must have the same values. An example 11876 shading map for such a camera is defined as: 11877 11878 android.lens.info.shadingMapSize = [ 4, 3 ] 11879 android.statistics.lensShadingMap = 11880 [ 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 11881 1.1, 1.1, 1.1, 1.1, 1.3, 1.3, 1.3, 1.3, 11882 1.2, 1.2, 1.2, 1.2, 1.1, 1.1, 1.1, 1.1, 11883 1.0, 1.0, 1.0, 1.0, 1.2, 1.2, 1.2, 1.2, 11884 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 11885 1.2, 1.2, 1.2, 1.2, 1.3, 1.3, 1.3, 1.3 ] 11886 11887 </details> 11888 </entry> 11889 <entry name="lensShadingMap" type="float" visibility="ndk_public" 11890 type_notes="2D array of float gain factors per channel to correct lens shading" 11891 container="array" hwlevel="full"> 11892 <array> 11893 <size>4</size> 11894 <size>n</size> 11895 <size>m</size> 11896 </array> 11897 <description>The shading map is a low-resolution floating-point map 11898 that lists the coefficients used to correct for vignetting and color shading, 11899 for each Bayer color channel of RAW image data.</description> 11900 <range>Each gain factor is &gt;= 1</range> 11901 <details> 11902 The map provided here is the same map that is used by the camera device to 11903 correct both color shading and vignetting for output non-RAW images. 11904 11905 When there is no lens shading correction applied to RAW 11906 output images (android.sensor.info.lensShadingApplied `==` 11907 false), this map is the complete lens shading correction 11908 map; when there is some lens shading correction applied to 11909 the RAW output image (android.sensor.info.lensShadingApplied 11910 `==` true), this map reports the remaining lens shading 11911 correction map that needs to be applied to get shading 11912 corrected images that match the camera device's output for 11913 non-RAW formats. 11914 11915 For a complete shading correction map, the least shaded 11916 section of the image will have a gain factor of 1; all 11917 other sections will have gains above 1. 11918 11919 When android.colorCorrection.mode = TRANSFORM_MATRIX, the map 11920 will take into account the colorCorrection settings. 11921 11922 The shading map is for the entire active pixel array, and is not 11923 affected by the crop region specified in the request. Each shading map 11924 entry is the value of the shading compensation map over a specific 11925 pixel on the sensor. Specifically, with a (N x M) resolution shading 11926 map, and an active pixel array size (W x H), shading map entry 11927 (x,y) ϵ (0 ... N-1, 0 ... M-1) is the value of the shading map at 11928 pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels. 11929 The map is assumed to be bilinearly interpolated between the sample points. 11930 11931 For a Bayer camera, the channel order is [R, Geven, Godd, B], where Geven is 11932 the green channel for the even rows of a Bayer pattern, and Godd is the odd rows. 11933 The shading map is stored in a fully interleaved format, and its size 11934 is provided in the camera static metadata by android.lens.info.shadingMapSize. 11935 11936 The shading map will generally have on the order of 30-40 rows and columns, 11937 and will be smaller than 64x64. 11938 11939 As an example, given a very small map for a Bayer camera defined as: 11940 11941 android.lens.info.shadingMapSize = [ 4, 3 ] 11942 android.statistics.lensShadingMap = 11943 [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2, 11944 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3, 11945 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0, 11946 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2, 11947 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2, 11948 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ] 11949 11950 The low-resolution scaling map images for each channel are 11951 (displayed using nearest-neighbor interpolation): 11952 11953  11954  11955  11956  11957 11958 As a visualization only, inverting the full-color map to recover an 11959 image of a gray wall (using bicubic interpolation for visual quality) 11960 as captured by the sensor gives: 11961 11962  11963 11964 For a MONOCHROME camera, all of the 2x2 channels must have the same values. An example 11965 shading map for such a camera is defined as: 11966 11967 android.lens.info.shadingMapSize = [ 4, 3 ] 11968 android.statistics.lensShadingMap = 11969 [ 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 11970 1.1, 1.1, 1.1, 1.1, 1.3, 1.3, 1.3, 1.3, 11971 1.2, 1.2, 1.2, 1.2, 1.1, 1.1, 1.1, 1.1, 11972 1.0, 1.0, 1.0, 1.0, 1.2, 1.2, 1.2, 1.2, 11973 1.3, 1.3, 1.3, 1.3, 1.2, 1.2, 1.2, 1.2, 11974 1.2, 1.2, 1.2, 1.2, 1.3, 1.3, 1.3, 1.3 ] 11975 11976 Note that the RAW image data might be subject to lens shading 11977 correction not reported on this map. Query 11978 android.sensor.info.lensShadingApplied to see if RAW image data has subject 11979 to lens shading correction. If android.sensor.info.lensShadingApplied 11980 is TRUE, the RAW image data is subject to partial or full lens shading 11981 correction. In the case full lens shading correction is applied to RAW 11982 images, the gain factor map reported in this key will contain all 1.0 gains. 11983 In other words, the map reported in this key is the remaining lens shading 11984 that needs to be applied on the RAW image to get images without lens shading 11985 artifacts. See android.request.maxNumOutputRaw for a list of RAW image 11986 formats. 11987 </details> 11988 <hal_details> 11989 The lens shading map calculation may depend on exposure and white balance statistics. 11990 When AE and AWB are in AUTO modes 11991 (android.control.aeMode `!=` OFF and android.control.awbMode `!=` OFF), the HAL 11992 may have all the information it need to generate most accurate lens shading map. When 11993 AE or AWB are in manual mode 11994 (android.control.aeMode `==` OFF or android.control.awbMode `==` OFF), the shading map 11995 may be adversely impacted by manual exposure or white balance parameters. To avoid 11996 generating unreliable shading map data, the HAL may choose to lock the shading map with 11997 the latest known good map generated when the AE and AWB are in AUTO modes. 11998 </hal_details> 11999 </entry> 12000 <entry name="predictedColorGains" type="float" 12001 visibility="hidden" 12002 deprecated="true" 12003 optional="true" 12004 type_notes="A 1D array of floats for 4 color channel gains" 12005 container="array"> 12006 <array> 12007 <size>4</size> 12008 </array> 12009 <description>The best-fit color channel gains calculated 12010 by the camera device's statistics units for the current output frame. 12011 </description> 12012 <deprecation_description> 12013 Never fully implemented or specified; do not use 12014 </deprecation_description> 12015 <details> 12016 This may be different than the gains used for this frame, 12017 since statistics processing on data from a new frame 12018 typically completes after the transform has already been 12019 applied to that frame. 12020 12021 The 4 channel gains are defined in Bayer domain, 12022 see android.colorCorrection.gains for details. 12023 12024 This value should always be calculated by the auto-white balance (AWB) block, 12025 regardless of the android.control.* current values. 12026 </details> 12027 </entry> 12028 <entry name="predictedColorTransform" type="rational" 12029 visibility="hidden" 12030 deprecated="true" 12031 optional="true" 12032 type_notes="3x3 rational matrix in row-major order" 12033 container="array"> 12034 <array> 12035 <size>3</size> 12036 <size>3</size> 12037 </array> 12038 <description>The best-fit color transform matrix estimate 12039 calculated by the camera device's statistics units for the current 12040 output frame.</description> 12041 <deprecation_description> 12042 Never fully implemented or specified; do not use 12043 </deprecation_description> 12044 <details>The camera device will provide the estimate from its 12045 statistics unit on the white balance transforms to use 12046 for the next frame. These are the values the camera device believes 12047 are the best fit for the current output frame. This may 12048 be different than the transform used for this frame, since 12049 statistics processing on data from a new frame typically 12050 completes after the transform has already been applied to 12051 that frame. 12052 12053 These estimates must be provided for all frames, even if 12054 capture settings and color transforms are set by the application. 12055 12056 This value should always be calculated by the auto-white balance (AWB) block, 12057 regardless of the android.control.* current values. 12058 </details> 12059 </entry> 12060 <entry name="sceneFlicker" type="byte" visibility="public" enum="true" 12061 hwlevel="full"> 12062 <enum> 12063 <value>NONE 12064 <notes>The camera device does not detect any flickering illumination 12065 in the current scene.</notes></value> 12066 <value>50HZ 12067 <notes>The camera device detects illumination flickering at 50Hz 12068 in the current scene.</notes></value> 12069 <value>60HZ 12070 <notes>The camera device detects illumination flickering at 60Hz 12071 in the current scene.</notes></value> 12072 </enum> 12073 <description>The camera device estimated scene illumination lighting 12074 frequency.</description> 12075 <details> 12076 Many light sources, such as most fluorescent lights, flicker at a rate 12077 that depends on the local utility power standards. This flicker must be 12078 accounted for by auto-exposure routines to avoid artifacts in captured images. 12079 The camera device uses this entry to tell the application what the scene 12080 illuminant frequency is. 12081 12082 When manual exposure control is enabled 12083 (`android.control.aeMode == OFF` or `android.control.mode == 12084 OFF`), the android.control.aeAntibandingMode doesn't perform 12085 antibanding, and the application can ensure it selects 12086 exposure times that do not cause banding issues by looking 12087 into this metadata field. See 12088 android.control.aeAntibandingMode for more details. 12089 12090 Reports NONE if there doesn't appear to be flickering illumination. 12091 </details> 12092 </entry> 12093 <clone entry="android.statistics.hotPixelMapMode" kind="controls"> 12094 </clone> 12095 <entry name="hotPixelMap" type="int32" visibility="public" 12096 type_notes="list of coordinates based on android.sensor.pixelArraySize" 12097 container="array" typedef="point"> 12098 <array> 12099 <size>2</size> 12100 <size>n</size> 12101 </array> 12102 <description> 12103 List of `(x, y)` coordinates of hot/defective pixels on the sensor. 12104 </description> 12105 <range> 12106 n <= number of pixels on the sensor. 12107 The `(x, y)` coordinates must be bounded by 12108 android.sensor.info.pixelArraySize. 12109 </range> 12110 <details> 12111 A coordinate `(x, y)` must lie between `(0, 0)`, and 12112 `(width - 1, height - 1)` (inclusive), which are the top-left and 12113 bottom-right of the pixel array, respectively. The width and 12114 height dimensions are given in android.sensor.info.pixelArraySize. 12115 This may include hot pixels that lie outside of the active array 12116 bounds given by android.sensor.info.activeArraySize. 12117 </details> 12118 <hal_details> 12119 A hotpixel map contains the coordinates of pixels on the camera 12120 sensor that do report valid values (usually due to defects in 12121 the camera sensor). This includes pixels that are stuck at certain 12122 values, or have a response that does not accurately encode the 12123 incoming light from the scene. 12124 12125 To avoid performance issues, there should be significantly fewer hot 12126 pixels than actual pixels on the camera sensor. 12127 </hal_details> 12128 <tag id="V1" /> 12129 <tag id="RAW" /> 12130 </entry> 12131 </dynamic> 12132 <controls> 12133 <entry name="lensShadingMapMode" type="byte" visibility="public" enum="true" hwlevel="full"> 12134 <enum> 12135 <value>OFF 12136 <notes>Do not include a lens shading map in the capture result.</notes></value> 12137 <value>ON 12138 <notes>Include a lens shading map in the capture result.</notes></value> 12139 </enum> 12140 <description>Whether the camera device will output the lens 12141 shading map in output result metadata.</description> 12142 <range>android.statistics.info.availableLensShadingMapModes</range> 12143 <details>When set to ON, 12144 android.statistics.lensShadingMap will be provided in 12145 the output result metadata. 12146 12147 ON is always supported on devices with the RAW capability. 12148 </details> 12149 <tag id="RAW" /> 12150 </entry> 12151 </controls> 12152 <dynamic> 12153 <clone entry="android.statistics.lensShadingMapMode" kind="controls"> 12154 </clone> 12155 </dynamic> 12156 <controls> 12157 <entry name="oisDataMode" type="byte" visibility="public" enum="true" hal_version="3.3"> 12158 <enum> 12159 <value>OFF 12160 <notes>Do not include OIS data in the capture result.</notes></value> 12161 <value>ON 12162 <notes>Include OIS data in the capture result.</notes> 12163 <sdk_notes>android.statistics.oisSamples provides OIS sample data in the 12164 output result metadata. 12165 </sdk_notes> 12166 <ndk_notes>android.statistics.oisTimestamps, android.statistics.oisXShifts, 12167 and android.statistics.oisYShifts provide OIS data in the output result metadata. 12168 </ndk_notes> 12169 </value> 12170 </enum> 12171 <description>A control for selecting whether optical stabilization (OIS) position 12172 information is included in output result metadata.</description> 12173 <range>android.statistics.info.availableOisDataModes</range> 12174 <details> 12175 Since optical image stabilization generally involves motion much faster than the duration 12176 of individual image exposure, multiple OIS samples can be included for a single capture 12177 result. For example, if the OIS reporting operates at 200 Hz, a typical camera operating 12178 at 30fps may have 6-7 OIS samples per capture result. This information can be combined 12179 with the rolling shutter skew to account for lens motion during image exposure in 12180 post-processing algorithms. 12181 </details> 12182 </entry> 12183 </controls> 12184 <dynamic> 12185 <clone entry="android.statistics.oisDataMode" kind="controls"> 12186 </clone> 12187 <entry name="oisTimestamps" type="int64" visibility="ndk_public" container="array" hal_version="3.3"> 12188 <array> 12189 <size>n</size> 12190 </array> 12191 <description> 12192 An array of timestamps of OIS samples, in nanoseconds. 12193 </description> 12194 <units>nanoseconds</units> 12195 <details> 12196 The array contains the timestamps of OIS samples. The timestamps are in the same 12197 timebase as and comparable to android.sensor.timestamp. 12198 </details> 12199 </entry> 12200 <entry name="oisXShifts" type="float" visibility="ndk_public" container="array" hal_version="3.3"> 12201 <array> 12202 <size>n</size> 12203 </array> 12204 <description> 12205 An array of shifts of OIS samples, in x direction. 12206 </description> 12207 <units>Pixels in active array.</units> 12208 <details> 12209 The array contains the amount of shifts in x direction, in pixels, based on OIS samples. 12210 A positive value is a shift from left to right in the pre-correction active array 12211 coordinate system. For example, if the optical center is (1000, 500) in pre-correction 12212 active array coordinates, a shift of (3, 0) puts the new optical center at (1003, 500). 12213 12214 The number of shifts must match the number of timestamps in 12215 android.statistics.oisTimestamps. 12216 12217 The OIS samples are not affected by whether lens distortion correction is enabled (on 12218 supporting devices). They are always reported in pre-correction active array coordinates, 12219 since the scaling of OIS shifts would depend on the specific spot on the sensor the shift 12220 is needed. 12221 </details> 12222 </entry> 12223 <entry name="oisYShifts" type="float" visibility="ndk_public" container="array" hal_version="3.3"> 12224 <array> 12225 <size>n</size> 12226 </array> 12227 <description> 12228 An array of shifts of OIS samples, in y direction. 12229 </description> 12230 <units>Pixels in active array.</units> 12231 <details> 12232 The array contains the amount of shifts in y direction, in pixels, based on OIS samples. 12233 A positive value is a shift from top to bottom in pre-correction active array coordinate 12234 system. For example, if the optical center is (1000, 500) in active array coordinates, a 12235 shift of (0, 5) puts the new optical center at (1000, 505). 12236 12237 The number of shifts must match the number of timestamps in 12238 android.statistics.oisTimestamps. 12239 12240 The OIS samples are not affected by whether lens distortion correction is enabled (on 12241 supporting devices). They are always reported in pre-correction active array coordinates, 12242 since the scaling of OIS shifts would depend on the specific spot on the sensor the shift 12243 is needed. 12244 </details> 12245 </entry> 12246 <entry name="oisSamples" type="float" visibility="java_public" synthetic="true" 12247 container="array" typedef="oisSample" hal_version="3.3"> 12248 <array> 12249 <size>n</size> 12250 </array> 12251 <description> 12252 An array of optical stabilization (OIS) position samples. 12253 </description> 12254 <details> 12255 Each OIS sample contains the timestamp and the amount of shifts in x and y direction, 12256 in pixels, of the OIS sample. 12257 12258 A positive value for a shift in x direction is a shift from left to right in the 12259 pre-correction active array coordinate system. For example, if the optical center is 12260 (1000, 500) in pre-correction active array coordinates, a shift of (3, 0) puts the new 12261 optical center at (1003, 500). 12262 12263 A positive value for a shift in y direction is a shift from top to bottom in 12264 pre-correction active array coordinate system. For example, if the optical center is 12265 (1000, 500) in active array coordinates, a shift of (0, 5) puts the new optical center at 12266 (1000, 505). 12267 12268 The OIS samples are not affected by whether lens distortion correction is enabled (on 12269 supporting devices). They are always reported in pre-correction active array coordinates, 12270 since the scaling of OIS shifts would depend on the specific spot on the sensor the shift 12271 is needed. 12272 </details> 12273 </entry> 12274 <entry name="lensIntrinsicsSamples" type="float" visibility="java_public" synthetic="true" 12275 container="array" typedef="lensIntrinsicsSample" aconfig_flag="concert_mode" 12276 hal_version="3.10"> 12277 <array> 12278 <size>n</size> 12279 </array> 12280 <description> 12281 An array of intra-frame lens intrinsic samples. 12282 </description> 12283 <details> 12284 Contains an array of intra-frame android.lens.intrinsicCalibration updates. This must 12285 not be confused or compared to android.statistics.oisSamples. Although OIS could be the 12286 main driver, all relevant factors such as focus distance and optical zoom must also 12287 be included. Do note that OIS samples must not be applied on top of the lens intrinsic 12288 samples. 12289 Support for this capture result can be queried via 12290 {@link android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys}. 12291 If available, clients can expect multiple samples per capture result. The specific 12292 amount will depend on current frame duration and sampling rate. Generally a sampling rate 12293 greater than or equal to 200Hz is considered sufficient for high quality results. 12294 </details> 12295 </entry> 12296 <entry name="lensIntrinsicTimestamps" type="int64" visibility="ndk_public" container="array" 12297 aconfig_flag="concert_mode" hal_version="3.10"> 12298 <array> 12299 <size>n</size> 12300 </array> 12301 <description> 12302 An array of timestamps of lens intrinsics samples, in nanoseconds. 12303 </description> 12304 <units>nanoseconds</units> 12305 <details> 12306 The array contains the timestamps of lens intrinsics samples. The timestamps are in the 12307 same timebase as and comparable to android.sensor.timestamp. 12308 </details> 12309 </entry> 12310 <entry name="lensIntrinsicSamples" type="float" visibility="ndk_public" 12311 container="array" aconfig_flag="concert_mode" hal_version="3.10"> 12312 <array> 12313 <size>5</size> 12314 <size>n</size> 12315 </array> 12316 <description> 12317 An array of intra-frame lens intrinsics. 12318 </description> 12319 <units> 12320 Pixels in the android.sensor.info.preCorrectionActiveArraySize coordinate system. 12321 </units> 12322 <details> 12323 The data layout and contents of individual array entries matches with 12324 android.lens.intrinsicCalibration. 12325 </details> 12326 </entry> 12327 </dynamic> 12328 </section> 12329 <section name="tonemap"> 12330 <controls> 12331 <entry name="curveBlue" type="float" visibility="ndk_public" 12332 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 12333 container="array" hwlevel="full"> 12334 <array> 12335 <size>n</size> 12336 <size>2</size> 12337 </array> 12338 <description>Tonemapping / contrast / gamma curve for the blue 12339 channel, to use when android.tonemap.mode is 12340 CONTRAST_CURVE.</description> 12341 <details>See android.tonemap.curveRed for more details.</details> 12342 </entry> 12343 <entry name="curveGreen" type="float" visibility="ndk_public" 12344 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 12345 container="array" hwlevel="full"> 12346 <array> 12347 <size>n</size> 12348 <size>2</size> 12349 </array> 12350 <description>Tonemapping / contrast / gamma curve for the green 12351 channel, to use when android.tonemap.mode is 12352 CONTRAST_CURVE.</description> 12353 <details>See android.tonemap.curveRed for more details.</details> 12354 </entry> 12355 <entry name="curveRed" type="float" visibility="ndk_public" 12356 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 12357 container="array" hwlevel="full"> 12358 <array> 12359 <size>n</size> 12360 <size>2</size> 12361 </array> 12362 <description>Tonemapping / contrast / gamma curve for the red 12363 channel, to use when android.tonemap.mode is 12364 CONTRAST_CURVE.</description> 12365 <range>0-1 on both input and output coordinates, normalized 12366 as a floating-point value such that 0 == black and 1 == white. 12367 </range> 12368 <details> 12369 Each channel's curve is defined by an array of control points: 12370 12371 android.tonemap.curveRed = 12372 [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ] 12373 2 <= N <= android.tonemap.maxCurvePoints 12374 12375 These are sorted in order of increasing `Pin`; it is 12376 required that input values 0.0 and 1.0 are included in the list to 12377 define a complete mapping. For input values between control points, 12378 the camera device must linearly interpolate between the control 12379 points. 12380 12381 Each curve can have an independent number of points, and the number 12382 of points can be less than max (that is, the request doesn't have to 12383 always provide a curve with number of points equivalent to 12384 android.tonemap.maxCurvePoints). 12385 12386 For devices with MONOCHROME capability, all three channels must have the same set of 12387 control points. 12388 12389 A few examples, and their corresponding graphical mappings; these 12390 only specify the red channel and the precision is limited to 4 12391 digits, for conciseness. 12392 12393 Linear mapping: 12394 12395 android.tonemap.curveRed = [ 0, 0, 1.0, 1.0 ] 12396 12397  12398 12399 Invert mapping: 12400 12401 android.tonemap.curveRed = [ 0, 1.0, 1.0, 0 ] 12402 12403  12404 12405 Gamma 1/2.2 mapping, with 16 control points: 12406 12407 android.tonemap.curveRed = [ 12408 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812, 12409 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072, 12410 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685, 12411 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ] 12412 12413  12414 12415 Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points: 12416 12417 android.tonemap.curveRed = [ 12418 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845, 12419 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130, 12420 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721, 12421 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ] 12422 12423  12424 </details> 12425 <hal_details> 12426 For good quality of mapping, at least 128 control points are 12427 preferred. 12428 12429 A typical use case of this would be a gamma-1/2.2 curve, with as many 12430 control points used as are available. 12431 </hal_details> 12432 </entry> 12433 <entry name="curve" type="float" visibility="java_public" synthetic="true" 12434 typedef="tonemapCurve" 12435 hwlevel="full"> 12436 <description>Tonemapping / contrast / gamma curve to use when android.tonemap.mode 12437 is CONTRAST_CURVE.</description> 12438 <details> 12439 The tonemapCurve consist of three curves for each of red, green, and blue 12440 channels respectively. The following example uses the red channel as an 12441 example. The same logic applies to green and blue channel. 12442 Each channel's curve is defined by an array of control points: 12443 12444 curveRed = 12445 [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ] 12446 2 <= N <= android.tonemap.maxCurvePoints 12447 12448 These are sorted in order of increasing `Pin`; it is always 12449 guaranteed that input values 0.0 and 1.0 are included in the list to 12450 define a complete mapping. For input values between control points, 12451 the camera device must linearly interpolate between the control 12452 points. 12453 12454 Each curve can have an independent number of points, and the number 12455 of points can be less than max (that is, the request doesn't have to 12456 always provide a curve with number of points equivalent to 12457 android.tonemap.maxCurvePoints). 12458 12459 For devices with MONOCHROME capability, all three channels must have the same set of 12460 control points. 12461 12462 A few examples, and their corresponding graphical mappings; these 12463 only specify the red channel and the precision is limited to 4 12464 digits, for conciseness. 12465 12466 Linear mapping: 12467 12468 curveRed = [ (0, 0), (1.0, 1.0) ] 12469 12470  12471 12472 Invert mapping: 12473 12474 curveRed = [ (0, 1.0), (1.0, 0) ] 12475 12476  12477 12478 Gamma 1/2.2 mapping, with 16 control points: 12479 12480 curveRed = [ 12481 (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812), 12482 (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072), 12483 (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685), 12484 (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ] 12485 12486  12487 12488 Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points: 12489 12490 curveRed = [ 12491 (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845), 12492 (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130), 12493 (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721), 12494 (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ] 12495 12496  12497 </details> 12498 <hal_details> 12499 This entry is created by the framework from the curveRed, curveGreen and 12500 curveBlue entries. 12501 </hal_details> 12502 </entry> 12503 <entry name="mode" type="byte" visibility="public" enum="true" 12504 hwlevel="full"> 12505 <enum> 12506 <value>CONTRAST_CURVE 12507 <notes>Use the tone mapping curve specified in 12508 the android.tonemap.curve* entries. 12509 12510 All color enhancement and tonemapping must be disabled, except 12511 for applying the tonemapping curve specified by 12512 android.tonemap.curve. 12513 12514 Must not slow down frame rate relative to raw 12515 sensor output. 12516 </notes> 12517 </value> 12518 <value>FAST 12519 <notes> 12520 Advanced gamma mapping and color enhancement may be applied, without 12521 reducing frame rate compared to raw sensor output. 12522 </notes> 12523 </value> 12524 <value>HIGH_QUALITY 12525 <notes> 12526 High-quality gamma mapping and color enhancement will be applied, at 12527 the cost of possibly reduced frame rate compared to raw sensor output. 12528 </notes> 12529 </value> 12530 <value>GAMMA_VALUE 12531 <notes> 12532 Use the gamma value specified in android.tonemap.gamma to perform 12533 tonemapping. 12534 12535 All color enhancement and tonemapping must be disabled, except 12536 for applying the tonemapping curve specified by android.tonemap.gamma. 12537 12538 Must not slow down frame rate relative to raw sensor output. 12539 </notes> 12540 </value> 12541 <value>PRESET_CURVE 12542 <notes> 12543 Use the preset tonemapping curve specified in 12544 android.tonemap.presetCurve to perform tonemapping. 12545 12546 All color enhancement and tonemapping must be disabled, except 12547 for applying the tonemapping curve specified by 12548 android.tonemap.presetCurve. 12549 12550 Must not slow down frame rate relative to raw sensor output. 12551 </notes> 12552 </value> 12553 </enum> 12554 <description>High-level global contrast/gamma/tonemapping control. 12555 </description> 12556 <range>android.tonemap.availableToneMapModes</range> 12557 <details> 12558 When switching to an application-defined contrast curve by setting 12559 android.tonemap.mode to CONTRAST_CURVE, the curve is defined 12560 per-channel with a set of `(in, out)` points that specify the 12561 mapping from input high-bit-depth pixel value to the output 12562 low-bit-depth value. Since the actual pixel ranges of both input 12563 and output may change depending on the camera pipeline, the values 12564 are specified by normalized floating-point numbers. 12565 12566 More-complex color mapping operations such as 3D color look-up 12567 tables, selective chroma enhancement, or other non-linear color 12568 transforms will be disabled when android.tonemap.mode is 12569 CONTRAST_CURVE. 12570 12571 When using either FAST or HIGH_QUALITY, the camera device will 12572 emit its own tonemap curve in android.tonemap.curve. 12573 These values are always available, and as close as possible to the 12574 actually used nonlinear/nonglobal transforms. 12575 12576 If a request is sent with CONTRAST_CURVE with the camera device's 12577 provided curve in FAST or HIGH_QUALITY, the image's tonemap will be 12578 roughly the same.</details> 12579 </entry> 12580 </controls> 12581 <static> 12582 <entry name="maxCurvePoints" type="int32" visibility="public" 12583 hwlevel="full"> 12584 <description>Maximum number of supported points in the 12585 tonemap curve that can be used for android.tonemap.curve. 12586 </description> 12587 <details> 12588 If the actual number of points provided by the application (in android.tonemap.curve*) is 12589 less than this maximum, the camera device will resample the curve to its internal 12590 representation, using linear interpolation. 12591 12592 The output curves in the result metadata may have a different number 12593 of points than the input curves, and will represent the actual 12594 hardware curves used as closely as possible when linearly interpolated. 12595 </details> 12596 <hal_details> 12597 This value must be at least 64. This should be at least 128. 12598 </hal_details> 12599 </entry> 12600 <entry name="availableToneMapModes" type="byte" visibility="public" 12601 type_notes="list of enums" container="array" typedef="enumList" hwlevel="full"> 12602 <array> 12603 <size>n</size> 12604 </array> 12605 <description> 12606 List of tonemapping modes for android.tonemap.mode that are supported by this camera 12607 device. 12608 </description> 12609 <range>Any value listed in android.tonemap.mode</range> 12610 <details> 12611 Camera devices that support the MANUAL_POST_PROCESSING capability will always contain 12612 at least one of below mode combinations: 12613 12614 * CONTRAST_CURVE, FAST and HIGH_QUALITY 12615 * GAMMA_VALUE, PRESET_CURVE, FAST and HIGH_QUALITY 12616 12617 This includes all FULL level devices. 12618 </details> 12619 <hal_details> 12620 HAL must support both FAST and HIGH_QUALITY if automatic tonemap control is available 12621 on the camera device, but the underlying implementation can be the same for both modes. 12622 That is, if the highest quality implementation on the camera device does not slow down 12623 capture rate, then FAST and HIGH_QUALITY will generate the same output. 12624 </hal_details> 12625 </entry> 12626 </static> 12627 <dynamic> 12628 <clone entry="android.tonemap.curveBlue" kind="controls"> 12629 </clone> 12630 <clone entry="android.tonemap.curveGreen" kind="controls"> 12631 </clone> 12632 <clone entry="android.tonemap.curveRed" kind="controls"> 12633 </clone> 12634 <clone entry="android.tonemap.curve" kind="controls"> 12635 </clone> 12636 <clone entry="android.tonemap.mode" kind="controls"> 12637 </clone> 12638 </dynamic> 12639 <controls> 12640 <entry name="gamma" type="float" visibility="public"> 12641 <description> Tonemapping curve to use when android.tonemap.mode is 12642 GAMMA_VALUE 12643 </description> 12644 <details> 12645 The tonemap curve will be defined the following formula: 12646 12647 * OUT = pow(IN, 1.0 / gamma) 12648 12649 where IN and OUT is the input pixel value scaled to range [0.0, 1.0], 12650 pow is the power function and gamma is the gamma value specified by this 12651 key. 12652 12653 The same curve will be applied to all color channels. The camera device 12654 may clip the input gamma value to its supported range. The actual applied 12655 value will be returned in capture result. 12656 12657 The valid range of gamma value varies on different devices, but values 12658 within [1.0, 5.0] are guaranteed not to be clipped. 12659 </details> 12660 </entry> 12661 <entry name="presetCurve" type="byte" visibility="public" enum="true"> 12662 <enum> 12663 <value>SRGB 12664 <notes>Tonemapping curve is defined by sRGB</notes> 12665 </value> 12666 <value>REC709 12667 <notes>Tonemapping curve is defined by ITU-R BT.709</notes> 12668 </value> 12669 </enum> 12670 <description> Tonemapping curve to use when android.tonemap.mode is 12671 PRESET_CURVE 12672 </description> 12673 <details> 12674 The tonemap curve will be defined by specified standard. 12675 12676 sRGB (approximated by 16 control points): 12677 12678  12679 12680 Rec. 709 (approximated by 16 control points): 12681 12682  12683 12684 Note that above figures show a 16 control points approximation of preset 12685 curves. Camera devices may apply a different approximation to the curve. 12686 </details> 12687 </entry> 12688 </controls> 12689 <dynamic> 12690 <clone entry="android.tonemap.gamma" kind="controls"> 12691 </clone> 12692 <clone entry="android.tonemap.presetCurve" kind="controls"> 12693 </clone> 12694 </dynamic> 12695 </section> 12696 <section name="led"> 12697 <controls> 12698 <entry name="transmit" type="byte" visibility="hidden" optional="true" 12699 enum="true" typedef="boolean"> 12700 <enum> 12701 <value>OFF</value> 12702 <value>ON</value> 12703 </enum> 12704 <description>This LED is nominally used to indicate to the user 12705 that the camera is powered on and may be streaming images back to the 12706 Application Processor. In certain rare circumstances, the OS may 12707 disable this when video is processed locally and not transmitted to 12708 any untrusted applications. 12709 12710 In particular, the LED *must* always be on when the data could be 12711 transmitted off the device. The LED *should* always be on whenever 12712 data is stored locally on the device. 12713 12714 The LED *may* be off if a trusted application is using the data that 12715 doesn't violate the above rules. 12716 </description> 12717 </entry> 12718 </controls> 12719 <dynamic> 12720 <clone entry="android.led.transmit" kind="controls"></clone> 12721 </dynamic> 12722 <static> 12723 <entry name="availableLeds" type="byte" visibility="hidden" optional="true" 12724 enum="true" 12725 container="array"> 12726 <array> 12727 <size>n</size> 12728 </array> 12729 <enum> 12730 <value>TRANSMIT 12731 <notes>android.led.transmit control is used.</notes> 12732 </value> 12733 </enum> 12734 <description>A list of camera LEDs that are available on this system. 12735 </description> 12736 </entry> 12737 </static> 12738 </section> 12739 <section name="info"> 12740 <static> 12741 <entry name="supportedHardwareLevel" type="byte" visibility="public" 12742 enum="true" hwlevel="legacy"> 12743 <enum> 12744 <value> 12745 LIMITED 12746 <notes> 12747 This camera device does not have enough capabilities to qualify as a `FULL` device or 12748 better. 12749 12750 Only the stream configurations listed in the `LEGACY` and `LIMITED` 12751 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#limited-level-additional-guaranteed-configurations) 12752 in the documentation are guaranteed to be supported. 12753 12754 All `LIMITED` devices support the `BACKWARDS_COMPATIBLE` capability, indicating basic 12755 support for color image capture. The only exception is that the device may 12756 alternatively support only the `DEPTH_OUTPUT` capability, if it can only output depth 12757 measurements and not color images. 12758 12759 `LIMITED` devices and above require the use of android.control.aePrecaptureTrigger 12760 to lock exposure metering (and calculate flash power, for cameras with flash) before 12761 capturing a high-quality still image. 12762 12763 A `LIMITED` device that only lists the `BACKWARDS_COMPATIBLE` capability is only 12764 required to support full-automatic operation and post-processing (`OFF` is not 12765 supported for android.control.aeMode, android.control.afMode, or 12766 android.control.awbMode) 12767 12768 Additional capabilities may optionally be supported by a `LIMITED`-level device, and 12769 can be checked for in android.request.availableCapabilities. 12770 </notes> 12771 </value> 12772 <value> 12773 FULL 12774 <notes> 12775 This camera device is capable of supporting advanced imaging applications. 12776 12777 The stream configurations listed in the `FULL`, `LEGACY` and `LIMITED` 12778 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#full-level-additional-guaranteed-configurations) 12779 in the documentation are guaranteed to be supported. 12780 12781 A `FULL` device will support below capabilities: 12782 12783 * `BURST_CAPTURE` capability (android.request.availableCapabilities contains 12784 `BURST_CAPTURE`) 12785 * Per frame control (android.sync.maxLatency `==` PER_FRAME_CONTROL) 12786 * Manual sensor control (android.request.availableCapabilities contains `MANUAL_SENSOR`) 12787 * Manual post-processing control (android.request.availableCapabilities contains 12788 `MANUAL_POST_PROCESSING`) 12789 * The required exposure time range defined in android.sensor.info.exposureTimeRange 12790 * The required maxFrameDuration defined in android.sensor.info.maxFrameDuration 12791 12792 Note: 12793 Pre-API level 23, FULL devices also supported arbitrary cropping region 12794 (android.scaler.croppingType `== FREEFORM`); this requirement was relaxed in API level 12795 23, and `FULL` devices may only support `CENTERED` cropping. 12796 </notes> 12797 </value> 12798 <value> 12799 LEGACY 12800 <notes> 12801 This camera device is running in backward compatibility mode. 12802 12803 Only the stream configurations listed in the `LEGACY` 12804 [table](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations) 12805 in the documentation are supported. 12806 12807 A `LEGACY` device does not support per-frame control, manual sensor control, manual 12808 post-processing, arbitrary cropping regions, and has relaxed performance constraints. 12809 No additional capabilities beyond `BACKWARD_COMPATIBLE` will ever be listed by a 12810 `LEGACY` device in android.request.availableCapabilities. 12811 12812 In addition, the android.control.aePrecaptureTrigger is not functional on `LEGACY` 12813 devices. Instead, every request that includes a JPEG-format output target is treated 12814 as triggering a still capture, internally executing a precapture trigger. This may 12815 fire the flash for flash power metering during precapture, and then fire the flash 12816 for the final capture, if a flash is available on the device and the AE mode is set to 12817 enable the flash. 12818 12819 Devices that initially shipped with Android version {@link 12820 android.os.Build.VERSION_CODES#Q Q} or newer will not include any LEGACY-level devices. 12821 </notes> 12822 </value> 12823 <value> 12824 3 12825 <notes> 12826 This camera device is capable of YUV reprocessing and RAW data capture, in addition to 12827 FULL-level capabilities. 12828 12829 The stream configurations listed in the `LEVEL_3`, `RAW`, `FULL`, `LEGACY` and 12830 `LIMITED` 12831 [tables](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#level-3-additional-guaranteed-configurations) 12832 in the documentation are guaranteed to be supported. 12833 12834 The following additional capabilities are guaranteed to be supported: 12835 12836 * `YUV_REPROCESSING` capability (android.request.availableCapabilities contains 12837 `YUV_REPROCESSING`) 12838 * `RAW` capability (android.request.availableCapabilities contains 12839 `RAW`) 12840 </notes> 12841 </value> 12842 <value hal_version="3.3"> 12843 EXTERNAL 12844 <notes> 12845 This camera device is backed by an external camera connected to this Android device. 12846 12847 The device has capability identical to a LIMITED level device, with the following 12848 exceptions: 12849 12850 * The device may not report lens/sensor related information such as 12851 - android.lens.focalLength 12852 - android.lens.info.hyperfocalDistance 12853 - android.sensor.info.physicalSize 12854 - android.sensor.info.whiteLevel 12855 - android.sensor.blackLevelPattern 12856 - android.sensor.info.colorFilterArrangement 12857 - android.sensor.rollingShutterSkew 12858 * The device will report 0 for android.sensor.orientation 12859 * The device has less guarantee on stable framerate, as the framerate partly depends 12860 on the external camera being used. 12861 </notes> 12862 </value> 12863 </enum> 12864 <description> 12865 Generally classifies the overall set of the camera device functionality. 12866 </description> 12867 <details> 12868 The supported hardware level is a high-level description of the camera device's 12869 capabilities, summarizing several capabilities into one field. Each level adds additional 12870 features to the previous one, and is always a strict superset of the previous level. 12871 The ordering is `LEGACY < LIMITED < FULL < LEVEL_3`. 12872 12873 Starting from `LEVEL_3`, the level enumerations are guaranteed to be in increasing 12874 numerical value as well. To check if a given device is at least at a given hardware level, 12875 the following code snippet can be used: 12876 12877 // Returns true if the device supports the required hardware level, or better. 12878 boolean isHardwareLevelSupported(CameraCharacteristics c, int requiredLevel) { 12879 final int[] sortedHwLevels = { 12880 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY, 12881 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL, 12882 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED, 12883 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL, 12884 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3 12885 }; 12886 int deviceLevel = c.get(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL); 12887 if (requiredLevel == deviceLevel) { 12888 return true; 12889 } 12890 12891 for (int sortedlevel : sortedHwLevels) { 12892 if (sortedlevel == requiredLevel) { 12893 return true; 12894 } else if (sortedlevel == deviceLevel) { 12895 return false; 12896 } 12897 } 12898 return false; // Should never reach here 12899 } 12900 12901 At a high level, the levels are: 12902 12903 * `LEGACY` devices operate in a backwards-compatibility mode for older 12904 Android devices, and have very limited capabilities. 12905 * `LIMITED` devices represent the 12906 baseline feature set, and may also include additional capabilities that are 12907 subsets of `FULL`. 12908 * `FULL` devices additionally support per-frame manual control of sensor, flash, lens and 12909 post-processing settings, and image capture at a high rate. 12910 * `LEVEL_3` devices additionally support YUV reprocessing and RAW image capture, along 12911 with additional output stream configurations. 12912 * `EXTERNAL` devices are similar to `LIMITED` devices with exceptions like some sensor or 12913 lens information not reported or less stable framerates. 12914 12915 See the individual level enums for full descriptions of the supported capabilities. The 12916 android.request.availableCapabilities entry describes the device's capabilities at a 12917 finer-grain level, if needed. In addition, many controls have their available settings or 12918 ranges defined in individual entries from {@link 12919 android.hardware.camera2.CameraCharacteristics|ACameraManager_getCameraCharacteristics}. 12920 12921 Some features are not part of any particular hardware level or capability and must be 12922 queried separately. These include: 12923 12924 * Calibrated timestamps (android.sensor.info.timestampSource `==` REALTIME) 12925 * Precision lens control (android.lens.info.focusDistanceCalibration `==` CALIBRATED) 12926 * Face detection (android.statistics.info.availableFaceDetectModes) 12927 * Optical or electrical image stabilization 12928 (android.lens.info.availableOpticalStabilization, 12929 android.control.availableVideoStabilizationModes) 12930 12931 </details> 12932 <hal_details> 12933 A camera HALv3 device can implement one of three possible operational modes; LIMITED, 12934 FULL, and LEVEL_3. 12935 12936 FULL support or better is expected from new higher-end devices. Limited 12937 mode has hardware requirements roughly in line with those for a camera HAL device v1 12938 implementation, and is expected from older or inexpensive devices. Each level is a strict 12939 superset of the previous level, and they share the same essential operational flow. 12940 12941 For full details refer to "S3. Operational Modes" in camera3.h 12942 12943 Camera HAL3+ must not implement LEGACY mode. It is there for backwards compatibility in 12944 the `android.hardware.camera2` user-facing API only on legacy HALv1 devices, and is 12945 implemented by the camera framework code. 12946 12947 EXTERNAL level devices have lower performance bar in CTS since the performance might depend 12948 on the external camera being used and is not fully controlled by the device manufacturer. 12949 The ITS test suite is exempted for the same reason. 12950 </hal_details> 12951 </entry> 12952 <entry name="version" type="byte" visibility="public" typedef="string" hal_version="3.3"> 12953 <description> 12954 A short string for manufacturer version information about the camera device, such as 12955 ISP hardware, sensors, etc. 12956 </description> 12957 <details> 12958 This can be used in {@link android.media.ExifInterface#TAG_IMAGE_DESCRIPTION TAG_IMAGE_DESCRIPTION} 12959 in jpeg EXIF. This key may be absent if no version information is available on the 12960 device. 12961 </details> 12962 <hal_details> 12963 The string must consist of only alphanumeric characters, punctuation, and 12964 whitespace, i.e. it must match regular expression "[\p{Alnum}\p{Punct}\p{Space}]*". 12965 It must not exceed 256 characters. 12966 </hal_details> 12967 </entry> 12968 <entry name="supportedBufferManagementVersion" type="byte" visibility="system" 12969 enum="true" hal_version="3.4"> 12970 <enum> 12971 <value> 12972 HIDL_DEVICE_3_5 12973 <notes> 12974 This camera device supports and opts in to the buffer management APIs provided by 12975 HIDL ICameraDevice version 3.5. 12976 </notes> 12977 </value> 12978 <value hal_version="3.10" aconfig_flag="session_hal_buf_manager"> 12979 SESSION_CONFIGURABLE 12980 <notes> 12981 This camera device supports the buffer management APIs provided by AIDL ICameraDevice 12982 version 1. It also supports the ICameraDeviceSession.configureStreamsV2 call to 12983 inform the camera framework whether HAL buffer manager must be used for the 12984 particular session configured. 12985 </notes> 12986 </value> 12987 </enum> 12988 <description> 12989 The version of buffer management API this camera device supports and opts into. 12990 </description> 12991 <details> 12992 When this key is not present, camera framework will interact with this camera device 12993 without any buffer management HAL API. When this key is present and camera framework 12994 supports the buffer management API version, camera framework will interact with camera 12995 HAL using such version of buffer management API. 12996 </details> 12997 </entry> 12998 <entry name="deviceStateSensorOrientationMap" type="int64" visibility="java_public" 12999 synthetic="true" optional="true" typedef="deviceStateSensorOrientationMap" 13000 hwlevel="limited"> 13001 <description>This lists the mapping between a device folding state and 13002 specific camera sensor orientation for logical cameras on a foldable device. 13003 </description> 13004 <details> 13005 Logical cameras on foldable devices can support sensors with different orientation 13006 values. The orientation value may need to change depending on the specific folding 13007 state. Information about the mapping between the device folding state and the 13008 sensor orientation can be obtained in 13009 {@link android.hardware.camera2.params.DeviceStateSensorOrientationMap}. 13010 Device state orientation maps are optional and maybe present on devices that support 13011 android.scaler.rotateAndCrop. 13012 </details> 13013 </entry> 13014 <entry name="deviceStateOrientations" type="int64" visibility="ndk_public" 13015 container="array" hwlevel="limited" hal_version="3.7"> 13016 <array> 13017 <size>2</size> 13018 <size>n</size> 13019 </array> 13020 <units>(device fold state, sensor orientation) x n</units> 13021 <details> 13022 HAL must populate the array with 13023 (hardware::camera::provider::V2_5::DeviceState, sensorOrientation) pairs for each 13024 supported device state bitwise combination. 13025 </details> 13026 </entry> 13027 <entry name="sessionConfigurationQueryVersion" type="int32" 13028 visibility="fwk_java_public" enum="true" typedef="versionCode" 13029 hwlevel="legacy" aconfig_flag="feature_combination_query" 13030 hal_version="3.10"> 13031 <enum> 13032 <value id="34">UPSIDE_DOWN_CAKE</value> 13033 <value id="35">VANILLA_ICE_CREAM</value> 13034 </enum> 13035 <description>The version of the session configuration query 13036 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#isSessionConfigurationSupported} 13037 and {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#getSessionCharacteristics} 13038 APIs. 13039 </description> 13040 <details>The possible values in this key correspond to the values defined in 13041 android.os.Build.VERSION_CODES. Each version defines a set of feature combinations the 13042 camera device must reliably report whether they are supported via 13043 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#isSessionConfigurationSupported}. 13044 It also defines the set of session specific keys in CameraCharacteristics when returned from 13045 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#getSessionCharacteristics}. 13046 The version is always less or equal to android.os.Build.VERSION.SDK_INT. 13047 13048 If set to UPSIDE_DOWN_CAKE, this camera device doesn't support the 13049 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup} API. 13050 Trying to create a CameraDeviceSetup instance throws an UnsupportedOperationException. 13051 13052 From VANILLA_ICE_CREAM onwards, the camera compliance tests verify a set of 13053 commonly used SessionConfigurations to ensure that the outputs of 13054 {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#isSessionConfigurationSupported} 13055 and {@link android.hardware.camera2.CameraDevice.CameraDeviceSetup#getSessionCharacteristics} 13056 are accurate. The application is encouraged to use these SessionConfigurations when turning on 13057 multiple features at the same time. 13058 13059 When set to VANILLA_ICE_CREAM, the combinations of the following configurations are verified 13060 by the compliance tests: 13061 13062 * A set of commonly used stream combinations: 13063 13064 Target 1 | Size | Target 2 | Size | 13065 :----------:|:-------------:|:---------------:|:------------:| 13066 PRIV | S1080P | | | 13067 PRIV | S720P | | | 13068 PRIV | S1080P | JPEG/JPEG_R | MAXIMUM_16_9 | 13069 PRIV | S1080P | JPEG/JPEG_R | UHD | 13070 PRIV | S1080P | JPEG/JPEG_R | S1440P | 13071 PRIV | S1080P | JPEG/JPEG_R | S1080P | 13072 PRIV | S1080P | PRIV | UHD | 13073 PRIV | S720P | JPEG/JPEG_R | MAXIMUM_16_9 | 13074 PRIV | S720P | JPEG/JPEG_R | UHD | 13075 PRIV | S720P | JPEG/JPEG_R | S1080P | 13076 PRIV | XVGA | JPEG/JPEG_R | MAXIMUM_4_3 | 13077 PRIV | S1080P_4_3 | JPEG/JPEG_R | MAXIMUM_4_3 | 13078 13079 * {@code MAXIMUM_4_3} refers to the camera device's maximum output resolution with 13080 4:3 aspect ratio for that format from {@code StreamConfigurationMap#getOutputSizes}. 13081 * {@code MAXIMUM_16_9} is the maximum output resolution with 16:9 aspect ratio. 13082 * {@code S1440P} refers to {@code 2560x1440 (16:9)}. 13083 * {@code S1080P} refers to {@code 1920x1080 (16:9)}. 13084 * {@code S720P} refers to {@code 1280x720 (16:9)}. 13085 * {@code UHD} refers to {@code 3840x2160 (16:9)}. 13086 * {@code XVGA} refers to {@code 1024x768 (4:3)}. 13087 * {@code S1080P_43} refers to {@code 1440x1080 (4:3)}. 13088 13089 * VIDEO_STABILIZATION_MODE: {OFF, PREVIEW} 13090 13091 * AE_TARGET_FPS_RANGE: { {\*, 30}, {\*, 60} } 13092 13093 * DYNAMIC_RANGE_PROFILE: {STANDARD, HLG10} 13094 13095 All of the above configurations can be set up with a SessionConfiguration. The list of 13096 OutputConfiguration contains the stream configurations and DYNAMIC_RANGE_PROFILE, and 13097 the AE_TARGET_FPS_RANGE and VIDEO_STABILIZATION_MODE are set as session parameters. 13098 </details> 13099 <hal_details> 13100 Preview stabilization must be orthogonal to other features. In other words, if preview 13101 stabilization is supported by the camera device, the return value of 13102 isStreamCombinationWithSettingsSupported for a particular combination must return 13103 the same value between stabilization off and preview stabilization on. This reduces the 13104 search space for feature combination queries. 13105 </hal_details> 13106 </entry> 13107 <entry name="deviceId" type="int32" visibility="fwk_only"> 13108 <description> 13109 Id of the device that owns this camera. 13110 </description> 13111 <details> 13112 In case of a virtual camera, this would be the id of the virtual device 13113 owning the camera. For any other camera, this key would not be present. 13114 Callers should assume {@link android.content.Context#DEVICE_ID_DEFAULT} 13115 in case this key is not present. 13116 </details> 13117 </entry> 13118 </static> 13119 </section> 13120 <section name="blackLevel"> 13121 <controls> 13122 <entry name="lock" type="byte" visibility="public" enum="true" 13123 typedef="boolean" hwlevel="full"> 13124 <enum> 13125 <value>OFF</value> 13126 <value>ON</value> 13127 </enum> 13128 <description> Whether black-level compensation is locked 13129 to its current values, or is free to vary.</description> 13130 <details>When set to `true` (ON), the values used for black-level 13131 compensation will not change until the lock is set to 13132 `false` (OFF). 13133 13134 Since changes to certain capture parameters (such as 13135 exposure time) may require resetting of black level 13136 compensation, the camera device must report whether setting 13137 the black level lock was successful in the output result 13138 metadata. 13139 13140 For example, if a sequence of requests is as follows: 13141 13142 * Request 1: Exposure = 10ms, Black level lock = OFF 13143 * Request 2: Exposure = 10ms, Black level lock = ON 13144 * Request 3: Exposure = 10ms, Black level lock = ON 13145 * Request 4: Exposure = 20ms, Black level lock = ON 13146 * Request 5: Exposure = 20ms, Black level lock = ON 13147 * Request 6: Exposure = 20ms, Black level lock = ON 13148 13149 And the exposure change in Request 4 requires the camera 13150 device to reset the black level offsets, then the output 13151 result metadata is expected to be: 13152 13153 * Result 1: Exposure = 10ms, Black level lock = OFF 13154 * Result 2: Exposure = 10ms, Black level lock = ON 13155 * Result 3: Exposure = 10ms, Black level lock = ON 13156 * Result 4: Exposure = 20ms, Black level lock = OFF 13157 * Result 5: Exposure = 20ms, Black level lock = ON 13158 * Result 6: Exposure = 20ms, Black level lock = ON 13159 13160 This indicates to the application that on frame 4, black 13161 levels were reset due to exposure value changes, and pixel 13162 values may not be consistent across captures. 13163 13164 The camera device will maintain the lock to the extent 13165 possible, only overriding the lock to OFF when changes to 13166 other request parameters require a black level recalculation 13167 or reset. 13168 </details> 13169 <hal_details> 13170 If for some reason black level locking is no longer possible 13171 (for example, the analog gain has changed, which forces 13172 black level offsets to be recalculated), then the HAL must 13173 override this request (and it must report 'OFF' when this 13174 does happen) until the next capture for which locking is 13175 possible again.</hal_details> 13176 <tag id="HAL2" /> 13177 </entry> 13178 </controls> 13179 <dynamic> 13180 <clone entry="android.blackLevel.lock" 13181 kind="controls"> 13182 <details> 13183 Whether the black level offset was locked for this frame. Should be 13184 ON if android.blackLevel.lock was ON in the capture request, unless 13185 a change in other capture settings forced the camera device to 13186 perform a black level reset. 13187 </details> 13188 </clone> 13189 </dynamic> 13190 </section> 13191 <section name="sync"> 13192 <dynamic> 13193 <entry name="frameNumber" type="int64" visibility="ndk_public" 13194 enum="true" hwlevel="legacy"> 13195 <enum> 13196 <value id="-1">CONVERGING 13197 <notes> 13198 The current result is not yet fully synchronized to any request. 13199 13200 Synchronization is in progress, and reading metadata from this 13201 result may include a mix of data that have taken effect since the 13202 last synchronization time. 13203 13204 In some future result, within android.sync.maxLatency frames, 13205 this value will update to the actual frame number frame number 13206 the result is guaranteed to be synchronized to (as long as the 13207 request settings remain constant). 13208 </notes> 13209 </value> 13210 <value id="-2">UNKNOWN 13211 <notes> 13212 The current result's synchronization status is unknown. 13213 13214 The result may have already converged, or it may be in 13215 progress. Reading from this result may include some mix 13216 of settings from past requests. 13217 13218 After a settings change, the new settings will eventually all 13219 take effect for the output buffers and results. However, this 13220 value will not change when that happens. Altering settings 13221 rapidly may provide outcomes using mixes of settings from recent 13222 requests. 13223 13224 This value is intended primarily for backwards compatibility with 13225 the older camera implementations (for android.hardware.Camera). 13226 </notes> 13227 </value> 13228 </enum> 13229 <description>The frame number corresponding to the last request 13230 with which the output result (metadata + buffers) has been fully 13231 synchronized.</description> 13232 <range>Either a non-negative value corresponding to a 13233 `frame_number`, or one of the two enums (CONVERGING / UNKNOWN). 13234 </range> 13235 <details> 13236 When a request is submitted to the camera device, there is usually a 13237 delay of several frames before the controls get applied. A camera 13238 device may either choose to account for this delay by implementing a 13239 pipeline and carefully submit well-timed atomic control updates, or 13240 it may start streaming control changes that span over several frame 13241 boundaries. 13242 13243 In the latter case, whenever a request's settings change relative to 13244 the previous submitted request, the full set of changes may take 13245 multiple frame durations to fully take effect. Some settings may 13246 take effect sooner (in less frame durations) than others. 13247 13248 While a set of control changes are being propagated, this value 13249 will be CONVERGING. 13250 13251 Once it is fully known that a set of control changes have been 13252 finished propagating, and the resulting updated control settings 13253 have been read back by the camera device, this value will be set 13254 to a non-negative frame number (corresponding to the request to 13255 which the results have synchronized to). 13256 13257 Older camera device implementations may not have a way to detect 13258 when all camera controls have been applied, and will always set this 13259 value to UNKNOWN. 13260 13261 FULL capability devices will always have this value set to the 13262 frame number of the request corresponding to this result. 13263 13264 _Further details_: 13265 13266 * Whenever a request differs from the last request, any future 13267 results not yet returned may have this value set to CONVERGING (this 13268 could include any in-progress captures not yet returned by the camera 13269 device, for more details see pipeline considerations below). 13270 * Submitting a series of multiple requests that differ from the 13271 previous request (e.g. r1, r2, r3 s.t. r1 != r2 != r3) 13272 moves the new synchronization frame to the last non-repeating 13273 request (using the smallest frame number from the contiguous list of 13274 repeating requests). 13275 * Submitting the same request repeatedly will not change this value 13276 to CONVERGING, if it was already a non-negative value. 13277 * When this value changes to non-negative, that means that all of the 13278 metadata controls from the request have been applied, all of the 13279 metadata controls from the camera device have been read to the 13280 updated values (into the result), and all of the graphics buffers 13281 corresponding to this result are also synchronized to the request. 13282 13283 _Pipeline considerations_: 13284 13285 Submitting a request with updated controls relative to the previously 13286 submitted requests may also invalidate the synchronization state 13287 of all the results corresponding to currently in-flight requests. 13288 13289 In other words, results for this current request and up to 13290 android.request.pipelineMaxDepth prior requests may have their 13291 android.sync.frameNumber change to CONVERGING. 13292 </details> 13293 <hal_details> 13294 Using UNKNOWN here is illegal unless android.sync.maxLatency 13295 is also UNKNOWN. 13296 13297 FULL capability devices should simply set this value to the 13298 `frame_number` of the request this result corresponds to. 13299 </hal_details> 13300 <tag id="V1" /> 13301 </entry> 13302 </dynamic> 13303 <static> 13304 <entry name="maxLatency" type="int32" visibility="public" enum="true" 13305 hwlevel="legacy"> 13306 <enum> 13307 <value id="0">PER_FRAME_CONTROL 13308 <notes> 13309 Every frame has the requests immediately applied. 13310 13311 Changing controls over multiple requests one after another will 13312 produce results that have those controls applied atomically 13313 each frame. 13314 13315 All FULL capability devices will have this as their maxLatency. 13316 </notes> 13317 </value> 13318 <value id="-1">UNKNOWN 13319 <notes> 13320 Each new frame has some subset (potentially the entire set) 13321 of the past requests applied to the camera settings. 13322 13323 By submitting a series of identical requests, the camera device 13324 will eventually have the camera settings applied, but it is 13325 unknown when that exact point will be. 13326 13327 All LEGACY capability devices will have this as their maxLatency. 13328 </notes> 13329 </value> 13330 </enum> 13331 <description> 13332 The maximum number of frames that can occur after a request 13333 (different than the previous) has been submitted, and before the 13334 result's state becomes synchronized. 13335 </description> 13336 <units>Frame counts</units> 13337 <range>A positive value, PER_FRAME_CONTROL, or UNKNOWN.</range> 13338 <details> 13339 This defines the maximum distance (in number of metadata results), 13340 between the frame number of the request that has new controls to apply 13341 and the frame number of the result that has all the controls applied. 13342 13343 In other words this acts as an upper boundary for how many frames 13344 must occur before the camera device knows for a fact that the new 13345 submitted camera settings have been applied in outgoing frames. 13346 </details> 13347 <hal_details> 13348 For example if maxLatency was 2, 13349 13350 initial request = X (repeating) 13351 request1 = X 13352 request2 = Y 13353 request3 = Y 13354 request4 = Y 13355 13356 where requestN has frameNumber N, and the first of the repeating 13357 initial request's has frameNumber F (and F < 1). 13358 13359 initial result = X' + { android.sync.frameNumber == F } 13360 result1 = X' + { android.sync.frameNumber == F } 13361 result2 = X' + { android.sync.frameNumber == CONVERGING } 13362 result3 = X' + { android.sync.frameNumber == CONVERGING } 13363 result4 = X' + { android.sync.frameNumber == 2 } 13364 13365 where resultN has frameNumber N. 13366 13367 Since `result4` has a `frameNumber == 4` and 13368 `android.sync.frameNumber == 2`, the distance is clearly 13369 `4 - 2 = 2`. 13370 13371 Use `frame_count` from camera3_request_t instead of 13372 android.request.frameCount or 13373 `{@link android.hardware.camera2.CaptureResult#getFrameNumber}`. 13374 13375 LIMITED devices are strongly encouraged to use a non-negative 13376 value. If UNKNOWN is used here then app developers do not have a way 13377 to know when sensor settings have been applied. 13378 </hal_details> 13379 <tag id="V1" /> 13380 </entry> 13381 </static> 13382 </section> 13383 <section name="reprocess"> 13384 <controls> 13385 <entry name="effectiveExposureFactor" type="float" visibility="java_public" hwlevel="limited"> 13386 <description> 13387 The amount of exposure time increase factor applied to the original output 13388 frame by the application processing before sending for reprocessing. 13389 </description> 13390 <units>Relative exposure time increase factor.</units> 13391 <range> &gt;= 1.0</range> 13392 <details> 13393 This is optional, and will be supported if the camera device supports YUV_REPROCESSING 13394 capability (android.request.availableCapabilities contains YUV_REPROCESSING). 13395 13396 For some YUV reprocessing use cases, the application may choose to filter the original 13397 output frames to effectively reduce the noise to the same level as a frame that was 13398 captured with longer exposure time. To be more specific, assuming the original captured 13399 images were captured with a sensitivity of S and an exposure time of T, the model in 13400 the camera device is that the amount of noise in the image would be approximately what 13401 would be expected if the original capture parameters had been a sensitivity of 13402 S/effectiveExposureFactor and an exposure time of T*effectiveExposureFactor, rather 13403 than S and T respectively. If the captured images were processed by the application 13404 before being sent for reprocessing, then the application may have used image processing 13405 algorithms and/or multi-frame image fusion to reduce the noise in the 13406 application-processed images (input images). By using the effectiveExposureFactor 13407 control, the application can communicate to the camera device the actual noise level 13408 improvement in the application-processed image. With this information, the camera 13409 device can select appropriate noise reduction and edge enhancement parameters to avoid 13410 excessive noise reduction (android.noiseReduction.mode) and insufficient edge 13411 enhancement (android.edge.mode) being applied to the reprocessed frames. 13412 13413 For example, for multi-frame image fusion use case, the application may fuse 13414 multiple output frames together to a final frame for reprocessing. When N image are 13415 fused into 1 image for reprocessing, the exposure time increase factor could be up to 13416 square root of N (based on a simple photon shot noise model). The camera device will 13417 adjust the reprocessing noise reduction and edge enhancement parameters accordingly to 13418 produce the best quality images. 13419 13420 This is relative factor, 1.0 indicates the application hasn't processed the input 13421 buffer in a way that affects its effective exposure time. 13422 13423 This control is only effective for YUV reprocessing capture request. For noise 13424 reduction reprocessing, it is only effective when `android.noiseReduction.mode != OFF`. 13425 Similarly, for edge enhancement reprocessing, it is only effective when 13426 `android.edge.mode != OFF`. 13427 </details> 13428 <tag id="REPROC" /> 13429 </entry> 13430 </controls> 13431 <dynamic> 13432 <clone entry="android.reprocess.effectiveExposureFactor" kind="controls"> 13433 </clone> 13434 </dynamic> 13435 <static> 13436 <entry name="maxCaptureStall" type="int32" visibility="java_public" hwlevel="limited"> 13437 <description> 13438 The maximal camera capture pipeline stall (in unit of frame count) introduced by a 13439 reprocess capture request. 13440 </description> 13441 <units>Number of frames.</units> 13442 <range> &lt;= 4</range> 13443 <details> 13444 The key describes the maximal interference that one reprocess (input) request 13445 can introduce to the camera simultaneous streaming of regular (output) capture 13446 requests, including repeating requests. 13447 13448 When a reprocessing capture request is submitted while a camera output repeating request 13449 (e.g. preview) is being served by the camera device, it may preempt the camera capture 13450 pipeline for at least one frame duration so that the camera device is unable to process 13451 the following capture request in time for the next sensor start of exposure boundary. 13452 When this happens, the application may observe a capture time gap (longer than one frame 13453 duration) between adjacent capture output frames, which usually exhibits as preview 13454 glitch if the repeating request output targets include a preview surface. This key gives 13455 the worst-case number of frame stall introduced by one reprocess request with any kind of 13456 formats/sizes combination. 13457 13458 If this key reports 0, it means a reprocess request doesn't introduce any glitch to the 13459 ongoing camera repeating request outputs, as if this reprocess request is never issued. 13460 13461 This key is supported if the camera device supports PRIVATE or YUV reprocessing ( 13462 i.e. android.request.availableCapabilities contains PRIVATE_REPROCESSING or 13463 YUV_REPROCESSING). 13464 </details> 13465 <tag id="REPROC" /> 13466 </entry> 13467 </static> 13468 </section> 13469 <section name="depth"> 13470 <static> 13471 <entry name="maxDepthSamples" type="int32" visibility="system" hwlevel="limited"> 13472 <description>Maximum number of points that a depth point cloud may contain. 13473 </description> 13474 <details> 13475 If a camera device supports outputting depth range data in the form of a depth point 13476 cloud ({@link android.graphics.ImageFormat#DEPTH_POINT_CLOUD}), this is the maximum 13477 number of points an output buffer may contain. 13478 13479 Any given buffer may contain between 0 and maxDepthSamples points, inclusive. 13480 If output in the depth point cloud format is not supported, this entry will 13481 not be defined. 13482 </details> 13483 <tag id="DEPTH" /> 13484 </entry> 13485 <entry name="availableDepthStreamConfigurations" type="int32" visibility="ndk_public" 13486 enum="true" container="array" typedef="streamConfiguration" hwlevel="limited"> 13487 <array> 13488 <size>n</size> 13489 <size>4</size> 13490 </array> 13491 <enum> 13492 <value>OUTPUT</value> 13493 <value>INPUT</value> 13494 </enum> 13495 <description>The available depth dataspace stream 13496 configurations that this camera device supports 13497 (i.e. format, width, height, output/input stream). 13498 </description> 13499 <details> 13500 These are output stream configurations for use with 13501 dataSpace HAL_DATASPACE_DEPTH. The configurations are 13502 listed as `(format, width, height, input?)` tuples. 13503 13504 Only devices that support depth output for at least 13505 the HAL_PIXEL_FORMAT_Y16 dense depth map may include 13506 this entry. 13507 13508 A device that also supports the HAL_PIXEL_FORMAT_BLOB 13509 sparse depth point cloud must report a single entry for 13510 the format in this list as `(HAL_PIXEL_FORMAT_BLOB, 13511 android.depth.maxDepthSamples, 1, OUTPUT)` in addition to 13512 the entries for HAL_PIXEL_FORMAT_Y16. 13513 </details> 13514 <tag id="DEPTH" /> 13515 </entry> 13516 <entry name="availableDepthMinFrameDurations" type="int64" visibility="ndk_public" 13517 container="array" typedef="streamConfigurationDuration" hwlevel="limited"> 13518 <array> 13519 <size>4</size> 13520 <size>n</size> 13521 </array> 13522 <description>This lists the minimum frame duration for each 13523 format/size combination for depth output formats. 13524 </description> 13525 <units>(format, width, height, ns) x n</units> 13526 <details> 13527 This should correspond to the frame duration when only that 13528 stream is active, with all processing (typically in android.*.mode) 13529 set to either OFF or FAST. 13530 13531 When multiple streams are used in a request, the minimum frame 13532 duration will be max(individual stream min durations). 13533 13534 The minimum frame duration of a stream (of a particular format, size) 13535 is the same regardless of whether the stream is input or output. 13536 13537 See android.sensor.frameDuration and 13538 android.scaler.availableStallDurations for more details about 13539 calculating the max frame rate. 13540 </details> 13541 <tag id="DEPTH" /> 13542 </entry> 13543 <entry name="availableDepthStallDurations" type="int64" visibility="ndk_public" 13544 container="array" typedef="streamConfigurationDuration" hwlevel="limited"> 13545 <array> 13546 <size>4</size> 13547 <size>n</size> 13548 </array> 13549 <description>This lists the maximum stall duration for each 13550 output format/size combination for depth streams. 13551 </description> 13552 <units>(format, width, height, ns) x n</units> 13553 <details> 13554 A stall duration is how much extra time would get added 13555 to the normal minimum frame duration for a repeating request 13556 that has streams with non-zero stall. 13557 13558 This functions similarly to 13559 android.scaler.availableStallDurations for depth 13560 streams. 13561 13562 All depth output stream formats may have a nonzero stall 13563 duration. 13564 </details> 13565 <tag id="DEPTH" /> 13566 </entry> 13567 <entry name="depthIsExclusive" type="byte" visibility="public" 13568 enum="true" typedef="boolean" hwlevel="limited"> 13569 <enum> 13570 <value>FALSE</value> 13571 <value>TRUE</value> 13572 </enum> 13573 <description>Indicates whether a capture request may target both a 13574 DEPTH16 / DEPTH_POINT_CLOUD output, and normal color outputs (such as 13575 YUV_420_888, JPEG, or RAW) simultaneously. 13576 </description> 13577 <details> 13578 If TRUE, including both depth and color outputs in a single 13579 capture request is not supported. An application must interleave color 13580 and depth requests. If FALSE, a single request can target both types 13581 of output. 13582 13583 Typically, this restriction exists on camera devices that 13584 need to emit a specific pattern or wavelength of light to 13585 measure depth values, which causes the color image to be 13586 corrupted during depth measurement. 13587 </details> 13588 </entry> 13589 <entry name="availableRecommendedDepthStreamConfigurations" type="int32" 13590 visibility="ndk_public" optional="true" container="array" 13591 typedef="recommendedStreamConfiguration" hal_version="3.4"> 13592 <array> 13593 <size>n</size> 13594 <size>5</size> 13595 </array> 13596 <description>Recommended depth stream configurations for common client use cases. 13597 </description> 13598 <details>Optional subset of the android.depth.availableDepthStreamConfigurations that 13599 contains similar tuples listed as 13600 (i.e. width, height, format, output/input stream, usecase bit field). 13601 Camera devices will be able to suggest particular depth stream configurations which are 13602 power and performance efficient for specific use cases. For more information about 13603 retrieving the suggestions see 13604 {@link android.hardware.camera2.CameraCharacteristics#getRecommendedStreamConfigurationMap}. 13605 </details> 13606 <ndk_details> 13607 For data representation please refer to 13608 android.scaler.availableRecommendedStreamConfigurations 13609 </ndk_details> 13610 <hal_details> 13611 Recommended depth configurations are expected to be declared with SNAPSHOT and/or 13612 ZSL if supported by the device. 13613 For additional details on how to declare recommended stream configurations, check 13614 android.scaler.availableRecommendedStreamConfigurations. 13615 For additional requirements on depth streams please consider 13616 android.depth.availableDepthStreamConfigurations. 13617 </hal_details> 13618 </entry> 13619 <entry name="availableDynamicDepthStreamConfigurations" type="int32" visibility="ndk_public" 13620 enum="true" container="array" typedef="streamConfiguration" hal_version="3.4"> 13621 <array> 13622 <size>n</size> 13623 <size>4</size> 13624 </array> 13625 <enum> 13626 <value>OUTPUT</value> 13627 <value>INPUT</value> 13628 </enum> 13629 <description>The available dynamic depth dataspace stream 13630 configurations that this camera device supports 13631 (i.e. format, width, height, output/input stream). 13632 </description> 13633 <details> 13634 These are output stream configurations for use with 13635 dataSpace DYNAMIC_DEPTH. The configurations are 13636 listed as `(format, width, height, input?)` tuples. 13637 13638 Only devices that support depth output for at least 13639 the HAL_PIXEL_FORMAT_Y16 dense depth map along with 13640 HAL_PIXEL_FORMAT_BLOB with the same size or size with 13641 the same aspect ratio can have dynamic depth dataspace 13642 stream configuration. android.depth.depthIsExclusive also 13643 needs to be set to FALSE. 13644 </details> 13645 <hal_details> 13646 Do not set this property directly. 13647 It is populated by camera framework and must not be set 13648 at the HAL layer. 13649 </hal_details> 13650 <tag id="DEPTH" /> 13651 </entry> 13652 <entry name="availableDynamicDepthMinFrameDurations" type="int64" visibility="ndk_public" 13653 container="array" typedef="streamConfigurationDuration" hal_version="3.4"> 13654 <array> 13655 <size>4</size> 13656 <size>n</size> 13657 </array> 13658 <description>This lists the minimum frame duration for each 13659 format/size combination for dynamic depth output streams. 13660 </description> 13661 <units>(format, width, height, ns) x n</units> 13662 <details> 13663 This should correspond to the frame duration when only that 13664 stream is active, with all processing (typically in android.*.mode) 13665 set to either OFF or FAST. 13666 13667 When multiple streams are used in a request, the minimum frame 13668 duration will be max(individual stream min durations). 13669 13670 The minimum frame duration of a stream (of a particular format, size) 13671 is the same regardless of whether the stream is input or output. 13672 </details> 13673 <hal_details> 13674 Do not set this property directly. 13675 It is populated by camera framework and must not be set 13676 at the HAL layer. 13677 </hal_details> 13678 <tag id="DEPTH" /> 13679 </entry> 13680 <entry name="availableDynamicDepthStallDurations" type="int64" visibility="ndk_public" 13681 container="array" typedef="streamConfigurationDuration" hal_version="3.4"> 13682 <array> 13683 <size>4</size> 13684 <size>n</size> 13685 </array> 13686 <description>This lists the maximum stall duration for each 13687 output format/size combination for dynamic depth streams. 13688 </description> 13689 <units>(format, width, height, ns) x n</units> 13690 <details> 13691 A stall duration is how much extra time would get added 13692 to the normal minimum frame duration for a repeating request 13693 that has streams with non-zero stall. 13694 13695 All dynamic depth output streams may have a nonzero stall 13696 duration. 13697 </details> 13698 <hal_details> 13699 Do not set this property directly. 13700 It is populated by camera framework and must not be set 13701 at the HAL layer. 13702 </hal_details> 13703 <tag id="DEPTH" /> 13704 </entry> 13705 <entry name="availableDepthStreamConfigurationsMaximumResolution" type="int32" 13706 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 13707 hal_version="3.6"> 13708 <array> 13709 <size>n</size> 13710 <size>4</size> 13711 </array> 13712 <enum> 13713 <value>OUTPUT</value> 13714 <value>INPUT</value> 13715 </enum> 13716 <description>The available depth dataspace stream 13717 configurations that this camera device supports 13718 (i.e. format, width, height, output/input stream) when a CaptureRequest is submitted with 13719 android.sensor.pixelMode set to 13720 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13721 </description> 13722 <details> 13723 Analogous to android.depth.availableDepthStreamConfigurations, for configurations which 13724 are applicable when android.sensor.pixelMode is set to 13725 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13726 </details> 13727 <tag id="DEPTH" /> 13728 </entry> 13729 <entry name="availableDepthMinFrameDurationsMaximumResolution" type="int64" 13730 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 13731 hal_version="3.6"> 13732 <array> 13733 <size>4</size> 13734 <size>n</size> 13735 </array> 13736 <description>This lists the minimum frame duration for each 13737 format/size combination for depth output formats when a CaptureRequest is submitted with 13738 android.sensor.pixelMode set to 13739 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13740 </description> 13741 <units>(format, width, height, ns) x n</units> 13742 <details> 13743 Analogous to android.depth.availableDepthMinFrameDurations, for configurations which 13744 are applicable when android.sensor.pixelMode is set to 13745 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13746 13747 See android.sensor.frameDuration and 13748 android.scaler.availableStallDurationsMaximumResolution for more details about 13749 calculating the max frame rate. 13750 </details> 13751 <tag id="DEPTH" /> 13752 </entry> 13753 <entry name="availableDepthStallDurationsMaximumResolution" type="int64" 13754 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 13755 hal_version="3.6"> 13756 <array> 13757 <size>4</size> 13758 <size>n</size> 13759 </array> 13760 <description>This lists the maximum stall duration for each 13761 output format/size combination for depth streams for CaptureRequests where 13762 android.sensor.pixelMode is set to 13763 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13764 </description> 13765 <units>(format, width, height, ns) x n</units> 13766 <details> 13767 Analogous to android.depth.availableDepthStallDurations, for configurations which 13768 are applicable when android.sensor.pixelMode is set to 13769 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13770 </details> 13771 <tag id="DEPTH" /> 13772 </entry> 13773 <entry name="availableDynamicDepthStreamConfigurationsMaximumResolution" type="int32" 13774 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 13775 hal_version="3.6"> 13776 <array> 13777 <size>n</size> 13778 <size>4</size> 13779 </array> 13780 <enum> 13781 <value>OUTPUT</value> 13782 <value>INPUT</value> 13783 </enum> 13784 <description>The available dynamic depth dataspace stream 13785 configurations that this camera device supports (i.e. format, width, height, 13786 output/input stream) for CaptureRequests where android.sensor.pixelMode is set to 13787 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13788 </description> 13789 <details> 13790 Analogous to android.depth.availableDynamicDepthStreamConfigurations, for configurations 13791 which are applicable when android.sensor.pixelMode is set to 13792 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13793 </details> 13794 <hal_details> 13795 Do not set this property directly. 13796 It is populated by camera framework and must not be set 13797 at the HAL layer. 13798 </hal_details> 13799 <tag id="DEPTH" /> 13800 </entry> 13801 <entry name="availableDynamicDepthMinFrameDurationsMaximumResolution" type="int64" 13802 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 13803 hal_version="3.6"> 13804 <array> 13805 <size>4</size> 13806 <size>n</size> 13807 </array> 13808 <description>This lists the minimum frame duration for each 13809 format/size combination for dynamic depth output streams for CaptureRequests where 13810 android.sensor.pixelMode is set to 13811 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13812 </description> 13813 <units>(format, width, height, ns) x n</units> 13814 <details> 13815 Analogous to android.depth.availableDynamicDepthMinFrameDurations, for configurations 13816 which are applicable when android.sensor.pixelMode is set to 13817 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13818 </details> 13819 <hal_details> 13820 Do not set this property directly. 13821 It is populated by camera framework and must not be set 13822 at the HAL layer. 13823 </hal_details> 13824 <tag id="DEPTH" /> 13825 </entry> 13826 <entry name="availableDynamicDepthStallDurationsMaximumResolution" type="int64" 13827 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 13828 hal_version="3.6"> 13829 <array> 13830 <size>4</size> 13831 <size>n</size> 13832 </array> 13833 <description>This lists the maximum stall duration for each 13834 output format/size combination for dynamic depth streams for CaptureRequests where 13835 android.sensor.pixelMode is set to 13836 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13837 </description> 13838 <units>(format, width, height, ns) x n</units> 13839 <details> 13840 Analogous to android.depth.availableDynamicDepthStallDurations, for configurations 13841 which are applicable when android.sensor.pixelMode is set to 13842 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13843 </details> 13844 <hal_details> 13845 Do not set this property directly. 13846 It is populated by camera framework and must not be set 13847 at the HAL layer. 13848 </hal_details> 13849 <tag id="DEPTH" /> 13850 </entry> 13851 </static> 13852 </section> 13853 <section name="logicalMultiCamera"> 13854 <static> 13855 <entry name="physicalIds" type="byte" visibility="ndk_public" 13856 container="array" hwlevel="limited" hal_version="3.3"> 13857 <array> 13858 <size>n</size> 13859 </array> 13860 <description>String containing the ids of the underlying physical cameras. 13861 </description> 13862 <units>UTF-8 null-terminated string</units> 13863 <details> 13864 For a logical camera, this is concatenation of all underlying physical camera IDs. 13865 The null terminator for physical camera ID must be preserved so that the whole string 13866 can be tokenized using '\0' to generate list of physical camera IDs. 13867 13868 For example, if the physical camera IDs of the logical camera are "2" and "3", the 13869 value of this tag will be ['2', '\0', '3', '\0']. 13870 13871 The number of physical camera IDs must be no less than 2. 13872 </details> 13873 <hal_details> 13874 Each physical camera id should uniquely identify a camera lens in the system. 13875 So if each camera lens only backs one logical camera, all camera IDs in the system, 13876 physical IDs or non-physical IDs, should be unique. 13877 13878 In rare cases, one camera lens backs two different logical cameras, the 13879 physicalIds of both logical cameras should contain a physical camera ID 13880 identifying that same camera lens. For example, if the mobile device has 3 rear facing 13881 cameras and no front facing cameras, and the 3 rear facing lenses may be modelled as 13882 2 logical cameras: 13883 13884 - "device@1.0/internal/10": physicalIds: "camera0", "camera42" 13885 - "device@1.0/internal/11": physicalIds: "camera1", "camera42" 13886 13887 In this case, the two logical cameras are conflicting devices because they are backed 13888 by a common lens. 13889 13890 Physical camera IDs can be an arbitrary string not containing '\0'. 13891 </hal_details> 13892 <tag id="LOGICALCAMERA" /> 13893 </entry> 13894 <entry name="sensorSyncType" type="byte" visibility="public" 13895 enum="true" hwlevel="limited" hal_version="3.3"> 13896 <enum> 13897 <value>APPROXIMATE 13898 <notes> 13899 A software mechanism is used to synchronize between the physical cameras. As a result, 13900 the timestamp of an image from a physical stream is only an approximation of the 13901 image sensor start-of-exposure time. 13902 </notes> 13903 </value> 13904 <value>CALIBRATED 13905 <notes> 13906 The camera device supports frame timestamp synchronization at the hardware level, 13907 and the timestamp of a physical stream image accurately reflects its 13908 start-of-exposure time. 13909 </notes> 13910 </value> 13911 </enum> 13912 <description>The accuracy of frame timestamp synchronization between physical cameras</description> 13913 <details> 13914 The accuracy of the frame timestamp synchronization determines the physical cameras' 13915 ability to start exposure at the same time. If the sensorSyncType is CALIBRATED, the 13916 physical camera sensors usually run in leader/follower mode where one sensor generates a 13917 timing signal for the other, so that their shutter time is synchronized. For APPROXIMATE 13918 sensorSyncType, the camera sensors usually run in leader/leader mode, where both sensors 13919 use their own timing generator, and there could be offset between their start of exposure. 13920 13921 In both cases, all images generated for a particular capture request still carry the same 13922 timestamps, so that they can be used to look up the matching frame number and 13923 onCaptureStarted callback. 13924 13925 This tag is only applicable if the logical camera device supports concurrent physical 13926 streams from different physical cameras. 13927 </details> 13928 <tag id="LOGICALCAMERA" /> 13929 </entry> 13930 </static> 13931 <dynamic> 13932 <entry name="activePhysicalId" type="byte" visibility="public" 13933 typedef="string" hal_version="3.4"> 13934 <description>String containing the ID of the underlying active physical camera. 13935 </description> 13936 <units>UTF-8 null-terminated string</units> 13937 <details> 13938 The ID of the active physical camera that's backing the logical camera. All camera 13939 streams and metadata that are not physical camera specific will be originating from this 13940 physical camera. 13941 13942 For a logical camera made up of physical cameras where each camera's lenses have 13943 different characteristics, the camera device may choose to switch between the physical 13944 cameras when application changes FOCAL_LENGTH or SCALER_CROP_REGION. 13945 At the time of lens switch, this result metadata reflects the new active physical camera 13946 ID. 13947 13948 This key will be available if the camera device advertises this key via {@link 13949 android.hardware.camera2.CameraCharacteristics#getAvailableCaptureResultKeys|ACAMERA_REQUEST_AVAILABLE_RESULT_KEYS}. 13950 When available, this must be one of valid physical IDs backing this logical multi-camera. 13951 If this key is not available for a logical multi-camera, the camera device implementation 13952 may still switch between different active physical cameras based on use case, but the 13953 current active physical camera information won't be available to the application. 13954 </details> 13955 <hal_details> 13956 Staring from HIDL ICameraDevice version 3.5, the tag must be available in the capture 13957 result metadata to indicate current active physical camera ID. 13958 </hal_details> 13959 <tag id="LOGICALCAMERA" /> 13960 </entry> 13961 <entry name="activePhysicalSensorCropRegion" type="int32" visibility="public" 13962 container="array" typedef="rectangle" aconfig_flag="concert_mode" hal_version="3.10"> 13963 <array> 13964 <size>4</size> 13965 </array> 13966 <description>The current region of the active physical sensor that will be read out for this 13967 capture.</description> 13968 <units>Pixel coordinates relative to 13969 android.sensor.info.activeArraySize or 13970 android.sensor.info.preCorrectionActiveArraySize of the currently 13971 android.logicalMultiCamera.activePhysicalId depending on distortion correction capability 13972 and mode</units> 13973 <details> 13974 This capture result matches with android.scaler.cropRegion on non-logical single 13975 camera sensor devices. In case of logical cameras that can switch between several 13976 physical devices in response to android.control.zoomRatio, this capture result will 13977 not behave like android.scaler.cropRegion and android.control.zoomRatio, where the 13978 combination of both reflects the effective zoom and crop of the logical camera output. 13979 Instead, this capture result value will describe the zoom and crop of the active physical 13980 device. Some examples of when the value of this capture result will change include 13981 switches between different physical lenses, switches between regular and maximum 13982 resolution pixel mode and going through the device digital or optical range. 13983 This capture result is similar to android.scaler.cropRegion with respect to distortion 13984 correction. When the distortion correction mode is OFF, the coordinate system follows 13985 android.sensor.info.preCorrectionActiveArraySize, with (0, 0) being the top-left pixel 13986 of the pre-correction active array. When the distortion correction mode is not OFF, 13987 the coordinate system follows android.sensor.info.activeArraySize, with (0, 0) being 13988 the top-left pixel of the active array. 13989 13990 For camera devices with the 13991 {@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_ULTRA_HIGH_RESOLUTION_SENSOR} 13992 capability or devices where {@link CameraCharacteristics#getAvailableCaptureRequestKeys} 13993 lists {@link CaptureRequest#SENSOR_PIXEL_MODE android.sensor.pixelMode} 13994 , the current active physical device 13995 android.sensor.info.activeArraySizeMaximumResolution / 13996 android.sensor.info.preCorrectionActiveArraySizeMaximumResolution must be used as the 13997 coordinate system for requests where android.sensor.pixelMode is set to 13998 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 13999 </details> 14000 <ndk_details> 14001 The data representation is int[4], which maps to (left, top, width, height). 14002 </ndk_details> 14003 <hal_details> 14004 The output streams must maintain square pixels at all 14005 times, no matter what the relative aspect ratios of the 14006 crop region and the stream are. Negative values for 14007 corner are allowed for raw output if full pixel array is 14008 larger than active pixel array. Width and height may be 14009 rounded to nearest larger supportable width, especially 14010 for raw output, where only a few fixed scales may be 14011 possible. 14012 </hal_details> 14013 <tag id="LOGICALCAMERA" /> 14014 </entry> 14015 </dynamic> 14016 </section> 14017 <section name="distortionCorrection"> 14018 <controls> 14019 <entry name="mode" type="byte" visibility="public" enum="true" hal_version="3.3"> 14020 <enum> 14021 <value>OFF 14022 <notes>No distortion correction is applied.</notes></value> 14023 <value>FAST <notes>Lens distortion correction is applied without reducing frame rate 14024 relative to sensor output. It may be the same as OFF if distortion correction would 14025 reduce frame rate relative to sensor.</notes></value> 14026 <value>HIGH_QUALITY <notes>High-quality distortion correction is applied, at the cost of 14027 possibly reduced frame rate relative to sensor output.</notes></value> 14028 </enum> 14029 <description>Mode of operation for the lens distortion correction block.</description> 14030 <range>android.distortionCorrection.availableModes</range> 14031 <details>The lens distortion correction block attempts to improve image quality by fixing 14032 radial, tangential, or other geometric aberrations in the camera device's optics. If 14033 available, the android.lens.distortion field documents the lens's distortion parameters. 14034 14035 OFF means no distortion correction is done. 14036 14037 FAST/HIGH_QUALITY both mean camera device determined distortion correction will be 14038 applied. HIGH_QUALITY mode indicates that the camera device will use the highest-quality 14039 correction algorithms, even if it slows down capture rate. FAST means the camera device 14040 will not slow down capture rate when applying correction. FAST may be the same as OFF if 14041 any correction at all would slow down capture rate. Every output stream will have a 14042 similar amount of enhancement applied. 14043 14044 The correction only applies to processed outputs such as YUV, Y8, JPEG, or DEPTH16; it is 14045 not applied to any RAW output. 14046 14047 This control will be on by default on devices that support this control. Applications 14048 disabling distortion correction need to pay extra attention with the coordinate system of 14049 metering regions, crop region, and face rectangles. When distortion correction is OFF, 14050 metadata coordinates follow the coordinate system of 14051 android.sensor.info.preCorrectionActiveArraySize. When distortion is not OFF, metadata 14052 coordinates follow the coordinate system of android.sensor.info.activeArraySize. The 14053 camera device will map these metadata fields to match the corrected image produced by the 14054 camera device, for both capture requests and results. However, this mapping is not very 14055 precise, since rectangles do not generally map to rectangles when corrected. Only linear 14056 scaling between the active array and precorrection active array coordinates is 14057 performed. Applications that require precise correction of metadata need to undo that 14058 linear scaling, and apply a more complete correction that takes into the account the app's 14059 own requirements. 14060 14061 The full list of metadata that is affected in this way by distortion correction is: 14062 14063 * android.control.afRegions 14064 * android.control.aeRegions 14065 * android.control.awbRegions 14066 * android.scaler.cropRegion 14067 * android.statistics.faces 14068 </details> 14069 </entry> 14070 </controls> 14071 <static> 14072 <entry name="availableModes" type="byte" visibility="public" 14073 type_notes="list of enums" container="array" typedef="enumList" hal_version="3.3"> 14074 <array> 14075 <size>n</size> 14076 </array> 14077 <description> 14078 List of distortion correction modes for android.distortionCorrection.mode that are 14079 supported by this camera device. 14080 </description> 14081 <range>Any value listed in android.distortionCorrection.mode</range> 14082 <details> 14083 No device is required to support this API; such devices will always list only 'OFF'. 14084 All devices that support this API will list both FAST and HIGH_QUALITY. 14085 </details> 14086 <hal_details> 14087 HAL must support both FAST and HIGH_QUALITY if distortion correction is available 14088 on the camera device, but the underlying implementation can be the same for both modes. 14089 That is, if the highest quality implementation on the camera device does not slow down 14090 capture rate, then FAST and HIGH_QUALITY will generate the same output. 14091 </hal_details> 14092 <tag id="V1" /> 14093 <tag id="REPROC" /> 14094 </entry> 14095 </static> 14096 <dynamic> 14097 <clone entry="android.distortionCorrection.mode" kind="controls" hal_version="3.3"> 14098 </clone> 14099 </dynamic> 14100 </section> 14101 <section name="heic"> 14102 <static> 14103 <namespace name="info"> 14104 <entry name="supported" type="byte" visibility="system" enum="true" 14105 typedef="boolean" hwlevel="limited" hal_version="3.4"> 14106 <enum> 14107 <value>FALSE</value> 14108 <value>TRUE</value> 14109 </enum> 14110 <description>Whether this camera device can support identical set of stream combinations 14111 involving HEIC image format, compared to the 14112 [table of combinations](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations) 14113 involving JPEG image format required for the device's hardware 14114 level and capabilities. 14115 </description> 14116 <details> 14117 All the static, control and dynamic metadata tags related to JPEG apply to HEIC formats 14118 as well. For example, the same android.jpeg.orientation and android.jpeg.quality are 14119 used to control the orientation and quality of the HEIC image. Configuring JPEG and 14120 HEIC streams at the same time is not supported. 14121 14122 If a camera device supports HEIC format (ISO/IEC 23008-12), not only does it 14123 support the existing mandatory stream 14124 [combinations](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#legacy-level-guaranteed-configurations) 14125 required for the device's hardware level and capabilities, it also 14126 supports swapping each JPEG stream with HEIC stream in all guaranteed combinations. 14127 14128 For every HEIC stream configured by the application, the camera framework sets up 2 14129 internal streams with camera HAL: 14130 14131 * A YUV_420_888 or IMPLEMENTATION_DEFINED HAL stream as input to HEIC or HEVC encoder. 14132 * A BLOB stream with JPEG_APPS_SEGMENTS dataspace to extract application markers 14133 including EXIF and thumbnail to be saved in HEIF container. 14134 14135 A camera device can output HEIC format to the application if and only if: 14136 14137 * The system contains a HEIC or HEVC encoder with constant quality mode, and 14138 * This tag is set to TRUE, meaning that camera HAL supports replacing JPEG streams in 14139 all mandatory stream combinations with a [YUV_420_888/IMPLEMENTATION_DEFINED stream + 14140 JPEG_APPS_SEGMENT BLOB stream] combo. 14141 14142 As an example, if the camera device's hardware level is LIMITED, and it supports HEIC, 14143 in addition to the required stream combinations, HAL must support below stream 14144 combinations as well: 14145 14146 * IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + JPEG_SEGMENTS_BLOB, 14147 * PRIV PREVIEW + IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + JPEG_SEGMENTS_BLOB, 14148 * YUV PREVIEW + IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + JPEG_SEGMENTS_BLOB, 14149 * PRIV PREVIEW + YUV PREVIEW + IMPLEMENTATION_DEFINED/YUV_420_888 MAXIMUM + 14150 JPEG_SEGMENTS_BLOB 14151 14152 The selection logic between YUV_420_888 and IMPLEMENTATION_DEFINED for HAL internal 14153 stream is as follows: 14154 14155 if (HEIC encoder exists and supports the size) { 14156 use IMPLEMENTATION_DEFINED with GRALLOC_USAGE_HW_IMAGE_ENCODER usage flag; 14157 } else { 14158 // HVC encoder exists 14159 if (size is less than framework predefined tile size) { 14160 use IMPLEMENTATINO_DEFINED with GRALLOC_USAGE_HW_VIDEO_ENCODER usage flag; 14161 } else { 14162 use YUV_420_888; 14163 } 14164 } 14165 </details> 14166 <tag id="HEIC" /> 14167 </entry> 14168 <entry name="maxJpegAppSegmentsCount" type="byte" visibility="system" 14169 hwlevel="limited" hal_version="3.4"> 14170 <description>The maximum number of Jpeg APP segments supported by the camera HAL device. 14171 </description> 14172 <details> 14173 The camera framework will use this value to derive the size of the BLOB buffer with 14174 JPEG_APP_SEGMENTS dataspace, with each APP segment occupying at most 64K bytes. If the 14175 value of this tag is n, the size of the framework allocated buffer will be: 14176 14177 n * (2 + 0xFFFF) + sizeof(struct CameraBlob) 14178 14179 where 2 is number of bytes for APP marker, 0xFFFF is the maximum size per APP segment 14180 (including segment size). 14181 14182 The value of this tag must be at least 1, and APP1 marker (0xFFE1) segment must be the 14183 first segment stored in the JPEG_APPS_SEGMENTS BLOB buffer. APP1 segment stores EXIF and 14184 thumbnail. 14185 14186 Since media encoder embeds the orientation in the metadata of the output image, to be 14187 consistent between main image and thumbnail, camera HAL must not rotate the thumbnail 14188 image data based on android.jpeg.orientation. The framework will write the orientation 14189 into EXIF and HEIC container. 14190 14191 APP1 segment is followed immediately by one or multiple APP2 segments, and APPn 14192 segments. After the HAL fills and returns the JPEG_APP_SEGMENTS buffer, the camera 14193 framework modifies the APP1 segment by filling in the EXIF tags that are related to 14194 main image bitstream and the tags that can be derived from capture result metadata, 14195 before saving them into the HEIC container. 14196 14197 The value of this tag must not be more than 16. 14198 </details> 14199 <tag id="HEIC" /> 14200 </entry> 14201 </namespace> 14202 14203 <entry name="availableHeicStreamConfigurations" type="int32" visibility="ndk_public" 14204 enum="true" container="array" typedef="streamConfiguration" 14205 hwlevel="limited" hal_version="3.4"> 14206 <array> 14207 <size>n</size> 14208 <size>4</size> 14209 </array> 14210 <enum> 14211 <value>OUTPUT</value> 14212 <value>INPUT</value> 14213 </enum> 14214 <description>The available HEIC (ISO/IEC 23008-12) stream 14215 configurations that this camera device supports 14216 (i.e. format, width, height, output/input stream). 14217 </description> 14218 <details> 14219 The configurations are listed as `(format, width, height, input?)` tuples. 14220 14221 If the camera device supports HEIC image format, it will support identical set of stream 14222 combinations involving HEIC image format, compared to the combinations involving JPEG 14223 image format as required by the device's hardware level and capabilities. 14224 14225 All the static, control, and dynamic metadata tags related to JPEG apply to HEIC formats. 14226 Configuring JPEG and HEIC streams at the same time is not supported. 14227 </details> 14228 <ndk_details> 14229 All the configuration tuples `(format, width, height, input?)` will contain 14230 AIMAGE_FORMAT_HEIC format as OUTPUT only. 14231 </ndk_details> 14232 <hal_details> 14233 These are output stream configurations for use with dataSpace HAL_DATASPACE_HEIF. 14234 14235 Do not set this property directly. It is populated by camera framework and must not be 14236 set by the HAL layer. 14237 </hal_details> 14238 <tag id="HEIC" /> 14239 </entry> 14240 <entry name="availableHeicMinFrameDurations" type="int64" visibility="ndk_public" 14241 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 14242 hal_version="3.4"> 14243 <array> 14244 <size>4</size> 14245 <size>n</size> 14246 </array> 14247 <description>This lists the minimum frame duration for each 14248 format/size combination for HEIC output formats. 14249 </description> 14250 <units>(format, width, height, ns) x n</units> 14251 <details> 14252 This should correspond to the frame duration when only that 14253 stream is active, with all processing (typically in android.*.mode) 14254 set to either OFF or FAST. 14255 14256 When multiple streams are used in a request, the minimum frame 14257 duration will be max(individual stream min durations). 14258 14259 See android.sensor.frameDuration and 14260 android.scaler.availableStallDurations for more details about 14261 calculating the max frame rate. 14262 </details> 14263 <hal_details> 14264 Do not set this property directly. It is populated by camera framework and must not be 14265 set by the HAL layer. 14266 </hal_details> 14267 <tag id="HEIC" /> 14268 </entry> 14269 <entry name="availableHeicStallDurations" type="int64" visibility="ndk_public" 14270 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 14271 hal_version="3.4"> 14272 <array> 14273 <size>4</size> 14274 <size>n</size> 14275 </array> 14276 <description>This lists the maximum stall duration for each 14277 output format/size combination for HEIC streams. 14278 </description> 14279 <units>(format, width, height, ns) x n</units> 14280 <details> 14281 A stall duration is how much extra time would get added 14282 to the normal minimum frame duration for a repeating request 14283 that has streams with non-zero stall. 14284 14285 This functions similarly to 14286 android.scaler.availableStallDurations for HEIC 14287 streams. 14288 14289 All HEIC output stream formats may have a nonzero stall 14290 duration. 14291 </details> 14292 <hal_details> 14293 Do not set this property directly. It is populated by camera framework and must not be 14294 set by the HAL layer. 14295 </hal_details> 14296 <tag id="HEIC" /> 14297 </entry> 14298 <entry name="availableHeicStreamConfigurationsMaximumResolution" type="int32" 14299 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 14300 hal_version="3.6"> 14301 <array> 14302 <size>n</size> 14303 <size>4</size> 14304 </array> 14305 <enum> 14306 <value>OUTPUT</value> 14307 <value>INPUT</value> 14308 </enum> 14309 <description>The available HEIC (ISO/IEC 23008-12) stream 14310 configurations that this camera device supports 14311 (i.e. format, width, height, output/input stream). 14312 </description> 14313 <details> 14314 Refer to android.heic.availableHeicStreamConfigurations for details. 14315 </details> 14316 <ndk_details> 14317 All the configuration tuples `(format, width, height, input?)` will contain 14318 AIMAGE_FORMAT_HEIC format as OUTPUT only. 14319 </ndk_details> 14320 <hal_details> 14321 These are output stream configurations for use with dataSpace HAL_DATASPACE_HEIF. 14322 14323 Do not set this property directly. It is populated by camera framework and must not be 14324 set by the HAL layer. 14325 </hal_details> 14326 <tag id="HEIC" /> 14327 </entry> 14328 <entry name="availableHeicMinFrameDurationsMaximumResolution" type="int64" 14329 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14330 hal_version="3.6"> 14331 <array> 14332 <size>4</size> 14333 <size>n</size> 14334 </array> 14335 <description>This lists the minimum frame duration for each 14336 format/size combination for HEIC output formats for CaptureRequests where 14337 android.sensor.pixelMode is set to 14338 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14339 </description> 14340 <units>(format, width, height, ns) x n</units> 14341 <details> 14342 Refer to android.heic.availableHeicMinFrameDurations for details. 14343 </details> 14344 <hal_details> 14345 Do not set this property directly. It is populated by camera framework and must not be 14346 set by the HAL layer. 14347 </hal_details> 14348 <tag id="HEIC" /> 14349 </entry> 14350 <entry name="availableHeicStallDurationsMaximumResolution" type="int64" 14351 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14352 hal_version="3.6"> 14353 <array> 14354 <size>4</size> 14355 <size>n</size> 14356 </array> 14357 <description>This lists the maximum stall duration for each 14358 output format/size combination for HEIC streams for CaptureRequests where 14359 android.sensor.pixelMode is set to 14360 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14361 </description> 14362 <units>(format, width, height, ns) x n</units> 14363 <details> 14364 Refer to android.heic.availableHeicStallDurations for details. 14365 </details> 14366 <hal_details> 14367 Do not set this property directly. It is populated by camera framework and must not be 14368 set by the HAL layer. 14369 </hal_details> 14370 <tag id="HEIC" /> 14371 </entry> 14372 </static> 14373 </section> 14374 <section name="automotive"> 14375 <static> 14376 <namespace name="lens"> 14377 <entry name="facing" type="byte" visibility="public" enum="true" container="array" 14378 hal_version="3.8"> 14379 <array> 14380 <size>n</size> 14381 </array> 14382 <enum> 14383 <value>EXTERIOR_OTHER 14384 <notes> 14385 The camera device faces the outside of the vehicle body frame but not exactly 14386 one of the exterior sides defined by this enum. Applications should determine 14387 the exact facing direction from android.lens.poseRotation and 14388 android.lens.poseTranslation. 14389 </notes> 14390 </value> 14391 <value>EXTERIOR_FRONT 14392 <notes> 14393 The camera device faces the front of the vehicle body frame. 14394 </notes> 14395 </value> 14396 <value>EXTERIOR_REAR 14397 <notes> 14398 The camera device faces the rear of the vehicle body frame. 14399 </notes> 14400 </value> 14401 <value>EXTERIOR_LEFT 14402 <notes> 14403 The camera device faces the left side of the vehicle body frame. 14404 </notes> 14405 </value> 14406 <value>EXTERIOR_RIGHT 14407 <notes> 14408 The camera device faces the right side of the vehicle body frame. 14409 </notes> 14410 </value> 14411 <value>INTERIOR_OTHER 14412 <notes> 14413 The camera device faces the inside of the vehicle body frame but not exactly 14414 one of seats described by this enum. Applications should determine the exact 14415 facing direction from android.lens.poseRotation and android.lens.poseTranslation. 14416 </notes> 14417 </value> 14418 <value>INTERIOR_SEAT_ROW_1_LEFT 14419 <notes> 14420 The camera device faces the left side seat of the first row. 14421 </notes> 14422 </value> 14423 <value>INTERIOR_SEAT_ROW_1_CENTER 14424 <notes> 14425 The camera device faces the center seat of the first row. 14426 </notes> 14427 </value> 14428 <value>INTERIOR_SEAT_ROW_1_RIGHT 14429 <notes> 14430 The camera device faces the right seat of the first row. 14431 </notes> 14432 </value> 14433 <value>INTERIOR_SEAT_ROW_2_LEFT 14434 <notes> 14435 The camera device faces the left side seat of the second row. 14436 </notes> 14437 </value> 14438 <value>INTERIOR_SEAT_ROW_2_CENTER 14439 <notes> 14440 The camera device faces the center seat of the second row. 14441 </notes> 14442 </value> 14443 <value>INTERIOR_SEAT_ROW_2_RIGHT 14444 <notes> 14445 The camera device faces the right side seat of the second row. 14446 </notes> 14447 </value> 14448 <value>INTERIOR_SEAT_ROW_3_LEFT 14449 <notes> 14450 The camera device faces the left side seat of the third row. 14451 </notes> 14452 </value> 14453 <value>INTERIOR_SEAT_ROW_3_CENTER 14454 <notes> 14455 The camera device faces the center seat of the third row. 14456 </notes> 14457 </value> 14458 <value>INTERIOR_SEAT_ROW_3_RIGHT 14459 <notes> 14460 The camera device faces the right seat of the third row. 14461 </notes> 14462 </value> 14463 </enum> 14464 <description> 14465 The direction of the camera faces relative to the vehicle body frame and the 14466 passenger seats. 14467 </description> 14468 <details> 14469 This enum defines the lens facing characteristic of the cameras on the automotive 14470 devices with locations android.automotive.location defines. If the system has 14471 FEATURE_AUTOMOTIVE, the camera will have this entry in its static metadata. 14472 14473 When android.automotive.location is INTERIOR, this has one or more INTERIOR_\* 14474 values or a single EXTERIOR_\* value. When this has more than one INTERIOR_\*, 14475 the first value must be the one for the seat closest to the optical axis. If this 14476 contains INTERIOR_OTHER, all other values will be ineffective. 14477 14478 When android.automotive.location is EXTERIOR_\* or EXTRA, this has a single 14479 EXTERIOR_\* value. 14480 14481 If a camera has INTERIOR_OTHER or EXTERIOR_OTHER, or more than one camera is at the 14482 same location and facing the same direction, their static metadata will list the 14483 following entries, so that applications can determine their lenses' exact facing 14484 directions: 14485 14486 * android.lens.poseReference 14487 * android.lens.poseRotation 14488 * android.lens.poseTranslation 14489 </details> 14490 </entry> 14491 </namespace> 14492 <entry name="location" type="byte" visibility="public" enum="true" hal_version="3.8"> 14493 <enum> 14494 <value>INTERIOR 14495 <notes> 14496 The camera device exists inside of the vehicle cabin. 14497 </notes> 14498 </value> 14499 <value>EXTERIOR_OTHER 14500 <notes> 14501 The camera exists outside of the vehicle body frame but not exactly on one of the 14502 exterior locations this enum defines. The applications should determine the exact 14503 location from android.lens.poseTranslation. 14504 </notes> 14505 </value> 14506 <value>EXTERIOR_FRONT 14507 <notes> 14508 The camera device exists outside of the vehicle body frame and on its front side. 14509 </notes> 14510 </value> 14511 <value>EXTERIOR_REAR 14512 <notes> 14513 The camera device exists outside of the vehicle body frame and on its rear side. 14514 </notes> 14515 </value> 14516 <value>EXTERIOR_LEFT 14517 <notes> 14518 The camera device exists outside and on left side of the vehicle body frame. 14519 </notes> 14520 </value> 14521 <value>EXTERIOR_RIGHT 14522 <notes> 14523 The camera device exists outside and on right side of the vehicle body frame. 14524 </notes> 14525 </value> 14526 <value>EXTRA_OTHER 14527 <notes> 14528 The camera device exists on an extra vehicle, such as the trailer, but not exactly 14529 on one of front, rear, left, or right side. Applications should determine the exact 14530 location from android.lens.poseTranslation. 14531 </notes> 14532 </value> 14533 <value>EXTRA_FRONT 14534 <notes> 14535 The camera device exists outside of the extra vehicle's body frame and on its front 14536 side. 14537 </notes> 14538 </value> 14539 <value>EXTRA_REAR 14540 <notes> 14541 The camera device exists outside of the extra vehicle's body frame and on its rear 14542 side. 14543 </notes> 14544 </value> 14545 <value>EXTRA_LEFT 14546 <notes> 14547 The camera device exists outside and on left side of the extra vehicle body. 14548 </notes> 14549 </value> 14550 <value>EXTRA_RIGHT 14551 <notes> 14552 The camera device exists outside and on right side of the extra vehicle body. 14553 </notes> 14554 </value> 14555 </enum> 14556 <description> 14557 Location of the cameras on the automotive devices. 14558 </description> 14559 <details> 14560 This enum defines the locations of the cameras relative to the vehicle body frame on 14561 [the automotive sensor coordinate system](https://source.android.com/devices/sensors/sensor-types#auto_axes). 14562 If the system has FEATURE_AUTOMOTIVE, the camera will have this entry in its static 14563 metadata. 14564 14565 * INTERIOR is the inside of the vehicle body frame (or the passenger cabin). 14566 * EXTERIOR is the outside of the vehicle body frame. 14567 * EXTRA is the extra vehicle such as a trailer. 14568 14569 Each side of the vehicle body frame on this coordinate system is defined as below: 14570 14571 * FRONT is where the Y-axis increases toward. 14572 * REAR is where the Y-axis decreases toward. 14573 * LEFT is where the X-axis decreases toward. 14574 * RIGHT is where the X-axis increases toward. 14575 14576 If the camera has either EXTERIOR_OTHER or EXTRA_OTHER, its static metadata will list 14577 the following entries, so that applications can determine the camera's exact location: 14578 14579 * android.lens.poseReference 14580 * android.lens.poseRotation 14581 * android.lens.poseTranslation 14582 </details> 14583 </entry> 14584 </static> 14585 </section> 14586 <section name="extension"> 14587 <controls> 14588 <entry name="strength" type="int32" visibility="fwk_java_public" hal_version="3.9"> 14589 <description>Strength of the extension post-processing effect 14590 </description> 14591 <range>0 - 100</range> 14592 <details> 14593 This control allows Camera extension clients to configure the strength of the applied 14594 extension effect. Strength equal to 0 means that the extension must not apply any 14595 post-processing and return a regular captured frame. Strength equal to 100 is the 14596 maximum level of post-processing. Values between 0 and 100 will have different effect 14597 depending on the extension type as described below: 14598 14599 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH BOKEH} - 14600 the strength is expected to control the amount of blur. 14601 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR HDR} and 14602 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT NIGHT} - 14603 the strength can control the amount of images fused and the brightness of the final image. 14604 * {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH FACE_RETOUCH} - 14605 the strength value will control the amount of cosmetic enhancement and skin 14606 smoothing. 14607 14608 The control will be supported if the capture request key is part of the list generated by 14609 {@link android.hardware.camera2.CameraExtensionCharacteristics#getAvailableCaptureRequestKeys}. 14610 The control is only defined and available to clients sending capture requests via 14611 {@link android.hardware.camera2.CameraExtensionSession}. 14612 If the client doesn't specify the extension strength value, then a default value will 14613 be set by the extension. Clients can retrieve the default value by checking the 14614 corresponding capture result. 14615 </details> 14616 </entry> 14617 </controls> 14618 <dynamic> 14619 <entry name="currentType" type="int32" visibility="fwk_java_public" hal_version="3.9"> 14620 <description>Contains the extension type of the currently active extension 14621 </description> 14622 <range>Extension type value listed in 14623 {@link android.hardware.camera2.CameraExtensionCharacteristics}</range> 14624 <details> 14625 The capture result will only be supported and included by camera extension 14626 {@link android.hardware.camera2.CameraExtensionSession sessions}. 14627 In case the extension session was configured to use 14628 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC AUTO}, 14629 then the extension type value will indicate the currently active extension like 14630 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR HDR}, 14631 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT NIGHT} etc. 14632 , and will never return 14633 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC AUTO}. 14634 In case the extension session was configured to use an extension different from 14635 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC AUTO}, 14636 then the result type will always match with the configured extension type. 14637 </details> 14638 </entry> 14639 <clone entry="android.extension.strength" kind="controls"> 14640 </clone> 14641 </dynamic> 14642 </section> 14643 <section name="jpegr"> 14644 <static> 14645 <entry name="availableJpegRStreamConfigurations" type="int32" visibility="ndk_public" 14646 enum="true" container="array" typedef="streamConfiguration" 14647 hwlevel="limited" hal_version="3.9"> 14648 <array> 14649 <size>n</size> 14650 <size>4</size> 14651 </array> 14652 <enum> 14653 <value>OUTPUT</value> 14654 <value>INPUT</value> 14655 </enum> 14656 <description>The available Jpeg/R stream 14657 configurations that this camera device supports 14658 (i.e. format, width, height, output/input stream). 14659 </description> 14660 <details> 14661 The configurations are listed as `(format, width, height, input?)` tuples. 14662 14663 If the camera device supports Jpeg/R, it will support the same stream combinations with 14664 Jpeg/R as it does with P010. The stream combinations with Jpeg/R (or P010) supported 14665 by the device is determined by the device's hardware level and capabilities. 14666 14667 All the static, control, and dynamic metadata tags related to JPEG apply to Jpeg/R formats. 14668 Configuring JPEG and Jpeg/R streams at the same time is not supported. 14669 </details> 14670 <ndk_details> 14671 All the configuration tuples `(format, width, height, input?)` will contain 14672 AIMAGE_FORMAT_JPEGR format as OUTPUT only. 14673 </ndk_details> 14674 </entry> 14675 <entry name="availableJpegRMinFrameDurations" type="int64" visibility="ndk_public" 14676 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 14677 hal_version="3.9"> 14678 <array> 14679 <size>4</size> 14680 <size>n</size> 14681 </array> 14682 <description>This lists the minimum frame duration for each 14683 format/size combination for Jpeg/R output formats. 14684 </description> 14685 <units>(format, width, height, ns) x n</units> 14686 <details> 14687 This should correspond to the frame duration when only that 14688 stream is active, with all processing (typically in android.*.mode) 14689 set to either OFF or FAST. 14690 14691 When multiple streams are used in a request, the minimum frame 14692 duration will be max(individual stream min durations). 14693 14694 See android.sensor.frameDuration and 14695 android.scaler.availableStallDurations for more details about 14696 calculating the max frame rate. 14697 </details> 14698 </entry> 14699 <entry name="availableJpegRStallDurations" type="int64" visibility="ndk_public" 14700 container="array" typedef="streamConfigurationDuration" hwlevel="limited" 14701 hal_version="3.9"> 14702 <array> 14703 <size>4</size> 14704 <size>n</size> 14705 </array> 14706 <description>This lists the maximum stall duration for each 14707 output format/size combination for Jpeg/R streams. 14708 </description> 14709 <units>(format, width, height, ns) x n</units> 14710 <details> 14711 A stall duration is how much extra time would get added 14712 to the normal minimum frame duration for a repeating request 14713 that has streams with non-zero stall. 14714 14715 This functions similarly to 14716 android.scaler.availableStallDurations for Jpeg/R 14717 streams. 14718 14719 All Jpeg/R output stream formats may have a nonzero stall 14720 duration. 14721 </details> 14722 </entry> 14723 <entry name="availableJpegRStreamConfigurationsMaximumResolution" type="int32" 14724 visibility="ndk_public" enum="true" container="array" typedef="streamConfiguration" 14725 hal_version="3.9"> 14726 <array> 14727 <size>n</size> 14728 <size>4</size> 14729 </array> 14730 <enum> 14731 <value>OUTPUT</value> 14732 <value>INPUT</value> 14733 </enum> 14734 <description>The available Jpeg/R stream 14735 configurations that this camera device supports 14736 (i.e. format, width, height, output/input stream). 14737 </description> 14738 <details> 14739 Refer to android.jpegr.availableJpegRStreamConfigurations for details. 14740 </details> 14741 <ndk_details> 14742 All the configuration tuples `(format, width, height, input?)` will contain 14743 AIMAGE_FORMAT_JPEG_R format as OUTPUT only. 14744 </ndk_details> 14745 </entry> 14746 <entry name="availableJpegRMinFrameDurationsMaximumResolution" type="int64" 14747 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14748 hal_version="3.9"> 14749 <array> 14750 <size>4</size> 14751 <size>n</size> 14752 </array> 14753 <description>This lists the minimum frame duration for each 14754 format/size combination for Jpeg/R output formats for CaptureRequests where 14755 android.sensor.pixelMode is set to 14756 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14757 </description> 14758 <units>(format, width, height, ns) x n</units> 14759 <details> 14760 Refer to android.jpegr.availableJpegRMinFrameDurations for details. 14761 </details> 14762 </entry> 14763 <entry name="availableJpegRStallDurationsMaximumResolution" type="int64" 14764 visibility="ndk_public" container="array" typedef="streamConfigurationDuration" 14765 hal_version="3.9"> 14766 <array> 14767 <size>4</size> 14768 <size>n</size> 14769 </array> 14770 <description>This lists the maximum stall duration for each 14771 output format/size combination for Jpeg/R streams for CaptureRequests where 14772 android.sensor.pixelMode is set to 14773 {@link android.hardware.camera2.CameraMetadata#SENSOR_PIXEL_MODE_MAXIMUM_RESOLUTION}. 14774 </description> 14775 <units>(format, width, height, ns) x n</units> 14776 <details> 14777 Refer to android.jpegr.availableJpegRStallDurations for details. 14778 </details> 14779 </entry> 14780 </static> 14781 </section> 14782 <section name="efv"> 14783 <static> 14784 <entry name="paddingZoomFactorRange" type="float" visibility="extension" 14785 optional="true" container="array" typedef="rangeFloat" aconfig_flag="concert_mode_api" 14786 hal_version="3.10"> 14787 <array> 14788 <size>2</size> 14789 </array> 14790 <description> 14791 Minimum and maximum padding zoom factors supported by this camera device for 14792 android.efv.paddingZoomFactor used for the 14793 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14794 extension. 14795 </description> 14796 <units>A pair of padding zoom factors in floating-points: 14797 (minPaddingZoomFactor, maxPaddingZoomFactor)</units> 14798 <range> 14799 1.0 < minPaddingZoomFactor <= maxPaddingZoomFactor 14800 </range> 14801 <details> 14802 The minimum and maximum padding zoom factors supported by the device for 14803 android.efv.paddingZoomFactor used as part of the 14804 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14805 extension feature. This extension specific camera characteristic can be queried using 14806 {@link android.hardware.camera2.CameraExtensionCharacteristics#get}. 14807 </details> 14808 </entry> 14809 </static> 14810 <controls> 14811 <entry name="paddingZoomFactor" type="float" visibility="extension" 14812 aconfig_flag="concert_mode_api" hal_version="3.10"> 14813 <description>Used to apply an additional digital zoom factor for the 14814 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14815 extension in {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} mode. 14816 </description> 14817 <range>android.efv.paddingZoomFactorRange</range> 14818 <details> 14819 For the {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14820 feature, an additional zoom factor is applied on top of the existing android.control.zoomRatio. 14821 This additional zoom factor serves as a buffer to provide more flexibility for the 14822 {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} 14823 mode. If android.efv.paddingZoomFactor is not set, the default will be used. 14824 The effectiveness of the stabilization may be influenced by the amount of padding zoom 14825 applied. A higher padding zoom factor can stabilize the target region more effectively 14826 with greater flexibility but may potentially impact image quality. Conversely, a lower 14827 padding zoom factor may be used to prioritize preserving image quality, albeit with less 14828 leeway in stabilizing the target region. It is recommended to set the 14829 android.efv.paddingZoomFactor to at least 1.5. 14830 14831 If android.efv.autoZoom is enabled, the requested android.efv.paddingZoomFactor will be overridden. 14832 android.efv.maxPaddingZoomFactor can be checked for more details on controlling the 14833 padding zoom factor during android.efv.autoZoom. 14834 </details> 14835 </entry> 14836 <entry name="autoZoom" type="byte" visibility="extension" enum="true" 14837 typedef="boolean" aconfig_flag="concert_mode_api" hal_version="3.10"> 14838 <enum> 14839 <value>TRUE</value> 14840 <value>FALSE</value> 14841 </enum> 14842 <description>Used to enable or disable auto zoom for the 14843 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14844 extension in {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} mode. 14845 </description> 14846 <details> 14847 Turn on auto zoom to let the 14848 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14849 feature decide at any given point a combination of 14850 android.control.zoomRatio and android.efv.paddingZoomFactor 14851 to keep the target region in view and stabilized. The combination chosen by the 14852 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14853 will equal the requested android.control.zoomRatio multiplied with the requested 14854 android.efv.paddingZoomFactor. A limit can be set on the padding zoom if wanting 14855 to control image quality further using android.efv.maxPaddingZoomFactor. 14856 </details> 14857 </entry> 14858 <entry name="maxPaddingZoomFactor" type="float" visibility="extension" 14859 aconfig_flag="concert_mode_api" hal_version="3.10"> 14860 <description>Used to limit the android.efv.paddingZoomFactor if 14861 android.efv.autoZoom is enabled for the 14862 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14863 extension in {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} mode. 14864 </description> 14865 <range>The range of android.efv.paddingZoomFactorRange. Use a value greater than or equal to 14866 the android.efv.paddingZoomFactor to effectively utilize this key.</range> 14867 <details> 14868 If android.efv.autoZoom is enabled, this key can be used to set a limit 14869 on the android.efv.paddingZoomFactor chosen by the 14870 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14871 extension in {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} mode 14872 to control image quality. 14873 </details> 14874 </entry> 14875 <entry name="stabilizationMode" type="int32" visibility="extension" enum="true" 14876 aconfig_flag="concert_mode_api" hal_version="3.10"> 14877 <enum> 14878 <value>OFF 14879 <notes> 14880 No stabilization. 14881 </notes></value> 14882 <value>GIMBAL 14883 <notes> 14884 Gimbal stabilization mode. 14885 </notes></value> 14886 <value>LOCKED 14887 <notes> 14888 Locked stabilization mode which uses the 14889 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14890 stabilization to directionally steady the target region. 14891 </notes></value> 14892 </enum> 14893 <description>Set the stabilization mode for the 14894 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14895 extension 14896 </description> 14897 <details> 14898 The desired stabilization mode. Gimbal stabilization mode provides simple, non-locked 14899 video stabilization. Locked mode uses the 14900 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14901 stabilization feature to fixate on the current region, utilizing it as the target area for 14902 stabilization. 14903 </details> 14904 </entry> 14905 <entry name="translateViewport" type="int32" visibility="extension" 14906 typedef="pairIntegerInteger" aconfig_flag="concert_mode_api" hal_version="3.10"> 14907 <description>Used to update the target region for the 14908 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14909 extension in {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} mode. 14910 </description> 14911 <range>android.util.Pair<Integer,Integer> represents the 14912 <Horizontal,Vertical> shift. The range for the horizontal shift is 14913 [-max(android.efv.paddingRegion-left), max(android.efv.paddingRegion-right)]. 14914 The range for the vertical shift is 14915 [-max(android.efv.paddingRegion-top), max(android.efv.paddingRegion-bottom)] 14916 </range> 14917 <details> 14918 A android.util.Pair<Integer,Integer> that represents the desired 14919 <Horizontal,Vertical> shift of the current locked view (or target region) in 14920 pixels. Negative values indicate left and upward shifts, while positive values indicate 14921 right and downward shifts in the active array coordinate system. 14922 </details> 14923 </entry> 14924 <entry name="rotateViewport" type="float" visibility="extension" 14925 aconfig_flag="concert_mode_api" hal_version="3.10"> 14926 <description>Representing the desired clockwise rotation 14927 of the target region in degrees for the 14928 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14929 extension in {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} mode. 14930 </description> 14931 <range>0 to 360 14932 </range> 14933 <details> 14934 Value representing the desired clockwise rotation of the target 14935 region in degrees. 14936 </details> 14937 </entry> 14938 </controls> 14939 <dynamic> 14940 <entry name="paddingRegion" type="int32" visibility="extension" container="array" 14941 aconfig_flag="concert_mode_api" hal_version="3.10"> 14942 <array> 14943 <size>4</size> 14944 </array> 14945 <description>The padding region for the 14946 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14947 extension in {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} mode. 14948 </description> 14949 <range>The padding is the number of remaining pixels of padding in each direction. 14950 The pixels reference the active array coordinate system. Negative values indicate the target 14951 region is out of bounds. The value for this key may be null for when the stabilization mode is 14952 in {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_OFF} 14953 or {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_GIMBAL} mode. 14954 </range> 14955 <details> 14956 An array [left, top, right, bottom] of the padding in pixels remaining on all four sides 14957 before the target region starts to go out of bounds. 14958 14959 The padding region denotes the area surrounding the stabilized target region within which 14960 the camera can be moved while maintaining the target region in view. As the camera moves, 14961 the padding region adjusts to represent the proximity of the target region to the 14962 boundary, which is the point at which the target region will start to go out of bounds. 14963 </details> 14964 </entry> 14965 <entry name="autoZoomPaddingRegion" type="int32" visibility="extension" 14966 container="array" aconfig_flag="concert_mode_api" hal_version="3.10"> 14967 <array> 14968 <size>4</size> 14969 </array> 14970 <description>The padding region when android.efv.autoZoom is enabled for the 14971 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14972 extension in {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} mode. 14973 </description> 14974 <range>The padding is the number of remaining pixels of padding in each direction 14975 when android.efv.autoZoom is enabled. Negative values indicate the target region is out of bounds. 14976 The value for this key may be null for when the android.efv.autoZoom is not enabled.</range> 14977 <details> 14978 An array [left, top, right, bottom] of the padding in pixels remaining on all four sides 14979 before the target region starts to go out of bounds. 14980 14981 This may differ from android.efv.paddingRegion as the field of view can change 14982 during android.efv.autoZoom, altering the boundary region and thus updating the padding between the 14983 target region and the boundary. 14984 </details> 14985 </entry> 14986 <entry name="targetCoordinates" type="float" visibility="extension" 14987 container="array" typedef="pointF" aconfig_flag="concert_mode_api" hal_version="3.10"> 14988 <array> 14989 <size>4</size> 14990 <size>n</size> 14991 </array> 14992 <description>List of coordinates representing the target region relative to the 14993 {@link android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE} 14994 for the 14995 {@link android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_EYES_FREE_VIDEOGRAPHY} 14996 extension in 14997 {@link android.hardware.camera2.CameraMetadata#EFV_STABILIZATION_MODE_LOCKED} mode. 14998 </description> 14999 <range>The list of target coordinates will define a region within the bounds of the 15000 {@link android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE} 15001 </range> 15002 <details> 15003 A list of android.graphics.PointF that define the coordinates of the target region 15004 relative to the 15005 {@link android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE}. 15006 The array represents the target region coordinates as: top-left, top-right, bottom-left, 15007 bottom-right. 15008 </details> 15009 </entry> 15010 <clone entry="android.efv.paddingZoomFactor" kind="controls"> 15011 </clone> 15012 <clone entry="android.efv.stabilizationMode" kind="controls"> 15013 </clone> 15014 <clone entry="android.efv.autoZoom" kind="controls"> 15015 </clone> 15016 <clone entry="android.efv.rotateViewport" kind="controls"> 15017 </clone> 15018 <clone entry="android.efv.translateViewport" kind="controls"> 15019 </clone> 15020 <clone entry="android.efv.maxPaddingZoomFactor" kind="controls"> 15021 </clone> 15022 </dynamic> 15023 </section> 15024 </namespace> 15025</metadata> 15026
