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/" 17 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 18 xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata_properties.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 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="FUTURE"> 37 Entry is under-specified and is not required for now. This is for book-keeping purpose, 38 do not implement or use it, it may be revised for future. 39 </tag> 40 </tags> 41 42 <types> 43 <typedef name="pairFloatFloat"> 44 <language name="java">android.util.Pair<Float,Float></language> 45 </typedef> 46 <typedef name="pairDoubleDouble"> 47 <language name="java">android.util.Pair<Double,Double></language> 48 </typedef> 49 <typedef name="rectangle"> 50 <language name="java">android.graphics.Rect</language> 51 </typedef> 52 <typedef name="size"> 53 <language name="java">android.util.Size</language> 54 </typedef> 55 <typedef name="string"> 56 <language name="java">String</language> 57 </typedef> 58 <typedef name="boolean"> 59 <language name="java">boolean</language> 60 </typedef> 61 <typedef name="imageFormat"> 62 <language name="java">int</language> 63 </typedef> 64 <typedef name="streamConfigurationMap"> 65 <language name="java">android.hardware.camera2.params.StreamConfigurationMap</language> 66 </typedef> 67 <typedef name="streamConfiguration"> 68 <language name="java">android.hardware.camera2.params.StreamConfiguration</language> 69 </typedef> 70 <typedef name="streamConfigurationDuration"> 71 <language name="java">android.hardware.camera2.params.StreamConfigurationDuration</language> 72 </typedef> 73 <typedef name="face"> 74 <language name="java">android.hardware.camera2.params.Face</language> 75 </typedef> 76 <typedef name="meteringRectangle"> 77 <language name="java">android.hardware.camera2.params.MeteringRectangle</language> 78 </typedef> 79 <typedef name="rangeFloat"> 80 <language name="java">android.util.Range<Float></language> 81 </typedef> 82 <typedef name="rangeInt"> 83 <language name="java">android.util.Range<Integer></language> 84 </typedef> 85 <typedef name="rangeLong"> 86 <language name="java">android.util.Range<Long></language> 87 </typedef> 88 <typedef name="colorSpaceTransform"> 89 <language name="java">android.hardware.camera2.params.ColorSpaceTransform</language> 90 </typedef> 91 <typedef name="rggbChannelVector"> 92 <language name="java">android.hardware.camera2.params.RggbChannelVector</language> 93 </typedef> 94 <typedef name="blackLevelPattern"> 95 <language name="java">android.hardware.camera2.params.BlackLevelPattern</language> 96 </typedef> 97 <typedef name="enumList"> 98 <language name="java">int</language> 99 </typedef> 100 <typedef name="sizeF"> 101 <language name="java">android.util.SizeF</language> 102 </typedef> 103 <typedef name="point"> 104 <language name="java">android.graphics.Point</language> 105 </typedef> 106 <typedef name="tonemapCurve"> 107 <language name="java">android.hardware.camera2.params.TonemapCurve</language> 108 </typedef> 109 <typedef name="lensShadingMap"> 110 <language name="java">android.hardware.camera2.params.LensShadingMap</language> 111 </typedef> 112 <typedef name="location"> 113 <language name="java">android.location.Location</language> 114 </typedef> 115 <typedef name="highSpeedVideoConfiguration"> 116 <language name="java">android.hardware.camera2.params.HighSpeedVideoConfiguration</language> 117 </typedef> 118 </types> 119 120 <namespace name="android"> 121 <section name="colorCorrection"> 122 <controls> 123 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 124 <enum> 125 <value>TRANSFORM_MATRIX 126 <notes>Use the android.colorCorrection.transform matrix 127 and android.colorCorrection.gains to do color conversion. 128 129 All advanced white balance adjustments (not specified 130 by our white balance pipeline) must be disabled. 131 132 If AWB is enabled with `android.control.awbMode != OFF`, then 133 TRANSFORM_MATRIX is ignored. The camera device will override 134 this value to either FAST or HIGH_QUALITY. 135 </notes> 136 </value> 137 <value>FAST 138 <notes>Color correction processing must not slow down 139 capture rate relative to sensor raw output. 140 141 Advanced white balance adjustments above and beyond 142 the specified white balance pipeline may be applied. 143 144 If AWB is enabled with `android.control.awbMode != OFF`, then 145 the camera device uses the last frame's AWB values 146 (or defaults if AWB has never been run). 147 </notes> 148 </value> 149 <value>HIGH_QUALITY 150 <notes>Color correction processing operates at improved 151 quality but reduced capture rate (relative to sensor raw 152 output). 153 154 Advanced white balance adjustments above and beyond 155 the specified white balance pipeline may be applied. 156 157 If AWB is enabled with `android.control.awbMode != OFF`, then 158 the camera device uses the last frame's AWB values 159 (or defaults if AWB has never been run). 160 </notes> 161 </value> 162 </enum> 163 164 <description> 165 The mode control selects how the image data is converted from the 166 sensor's native color into linear sRGB color. 167 </description> 168 <details> 169 When auto-white balance (AWB) is enabled with android.control.awbMode, this 170 control is overridden by the AWB routine. When AWB is disabled, the 171 application controls how the color mapping is performed. 172 173 We define the expected processing pipeline below. For consistency 174 across devices, this is always the case with TRANSFORM_MATRIX. 175 176 When either FULL or HIGH_QUALITY is used, the camera device may 177 do additional processing but android.colorCorrection.gains and 178 android.colorCorrection.transform will still be provided by the 179 camera device (in the results) and be roughly correct. 180 181 Switching to TRANSFORM_MATRIX and using the data provided from 182 FAST or HIGH_QUALITY will yield a picture with the same white point 183 as what was produced by the camera device in the earlier frame. 184 185 The expected processing pipeline is as follows: 186 187  188 189 The white balance is encoded by two values, a 4-channel white-balance 190 gain vector (applied in the Bayer domain), and a 3x3 color transform 191 matrix (applied after demosaic). 192 193 The 4-channel white-balance gains are defined as: 194 195 android.colorCorrection.gains = [ R G_even G_odd B ] 196 197 where `G_even` is the gain for green pixels on even rows of the 198 output, and `G_odd` is the gain for green pixels on the odd rows. 199 These may be identical for a given camera device implementation; if 200 the camera device does not support a separate gain for even/odd green 201 channels, it will use the `G_even` value, and write `G_odd` equal to 202 `G_even` in the output result metadata. 203 204 The matrices for color transforms are defined as a 9-entry vector: 205 206 android.colorCorrection.transform = [ I0 I1 I2 I3 I4 I5 I6 I7 I8 ] 207 208 which define a transform from input sensor colors, `P_in = [ r g b ]`, 209 to output linear sRGB, `P_out = [ r' g' b' ]`, 210 211 with colors as follows: 212 213 r' = I0r + I1g + I2b 214 g' = I3r + I4g + I5b 215 b' = I6r + I7g + I8b 216 217 Both the input and output value ranges must match. Overflow/underflow 218 values are clipped to fit within the range. 219 </details> 220 </entry> 221 <entry name="transform" type="rational" visibility="public" 222 type_notes="3x3 rational matrix in row-major order" 223 container="array" typedef="colorSpaceTransform" hwlevel="full"> 224 <array> 225 <size>3</size> 226 <size>3</size> 227 </array> 228 <description>A color transform matrix to use to transform 229 from sensor RGB color space to output linear sRGB color space. 230 </description> 231 <units>Unitless scale factors</units> 232 <details>This matrix is either set by the camera device when the request 233 android.colorCorrection.mode is not TRANSFORM_MATRIX, or 234 directly by the application in the request when the 235 android.colorCorrection.mode is TRANSFORM_MATRIX. 236 237 In the latter case, the camera device may round the matrix to account 238 for precision issues; the final rounded matrix should be reported back 239 in this matrix result metadata. The transform should keep the magnitude 240 of the output color values within `[0, 1.0]` (assuming input color 241 values is within the normalized range `[0, 1.0]`), or clipping may occur. 242 </details> 243 </entry> 244 <entry name="gains" type="float" visibility="public" 245 type_notes="A 1D array of floats for 4 color channel gains" 246 container="array" typedef="rggbChannelVector" hwlevel="full"> 247 <array> 248 <size>4</size> 249 </array> 250 <description>Gains applying to Bayer raw color channels for 251 white-balance.</description> 252 <units>Unitless gain factors</units> 253 <details> 254 These per-channel gains are either set by the camera device 255 when the request android.colorCorrection.mode is not 256 TRANSFORM_MATRIX, or directly by the application in the 257 request when the android.colorCorrection.mode is 258 TRANSFORM_MATRIX. 259 260 The gains in the result metadata are the gains actually 261 applied by the camera device to the current frame. 262 </details> 263 <hal_details> 264 The 4-channel white-balance gains are defined in 265 the order of `[R G_even G_odd B]`, where `G_even` is the gain 266 for green pixels on even rows of the output, and `G_odd` 267 is the gain for green pixels on the odd rows. 268 269 If a HAL does not support a separate gain for even/odd green 270 channels, it must use the `G_even` value, and write 271 `G_odd` equal to `G_even` in the output result metadata. 272 </hal_details> 273 </entry> 274 <entry name="aberrationMode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 275 <enum> 276 <value>OFF 277 <notes> 278 No aberration correction is applied. 279 </notes> 280 </value> 281 <value>FAST 282 <notes> 283 Aberration correction will not slow down capture rate 284 relative to sensor raw output. 285 </notes> 286 </value> 287 <value>HIGH_QUALITY 288 <notes> 289 Aberration correction operates at improved quality but reduced 290 capture rate (relative to sensor raw output). 291 </notes> 292 </value> 293 </enum> 294 <description> 295 Mode of operation for the chromatic aberration correction algorithm. 296 </description> 297 <range>android.colorCorrection.availableAberrationModes</range> 298 <details> 299 Chromatic (color) aberration is caused by the fact that different wavelengths of light 300 can not focus on the same point after exiting from the lens. This metadata defines 301 the high level control of chromatic aberration correction algorithm, which aims to 302 minimize the chromatic artifacts that may occur along the object boundaries in an 303 image. 304 305 FAST/HIGH_QUALITY both mean that camera device determined aberration 306 correction will be applied. HIGH_QUALITY mode indicates that the camera device will 307 use the highest-quality aberration correction algorithms, even if it slows down 308 capture rate. FAST means the camera device will not slow down capture rate when 309 applying aberration correction. 310 311 LEGACY devices will always be in FAST mode. 312 </details> 313 </entry> 314 </controls> 315 <dynamic> 316 <clone entry="android.colorCorrection.mode" kind="controls"> 317 </clone> 318 <clone entry="android.colorCorrection.transform" kind="controls"> 319 </clone> 320 <clone entry="android.colorCorrection.gains" kind="controls"> 321 </clone> 322 <clone entry="android.colorCorrection.aberrationMode" kind="controls"> 323 </clone> 324 </dynamic> 325 <static> 326 <entry name="availableAberrationModes" type="byte" visibility="public" 327 type_notes="list of enums" container="array" typedef="enumList" hwlevel="legacy"> 328 <array> 329 <size>n</size> 330 </array> 331 <description> 332 List of aberration correction modes for android.colorCorrection.aberrationMode that are 333 supported by this camera device. 334 </description> 335 <range>Any value listed in android.colorCorrection.aberrationMode</range> 336 <details> 337 This key lists the valid modes for android.colorCorrection.aberrationMode. If no 338 aberration correction modes are available for a device, this list will solely include 339 OFF mode. All camera devices will support either OFF or FAST mode. 340 341 Camera devices that support the MANUAL_POST_PROCESSING capability will always list 342 OFF mode. This includes all FULL level devices. 343 344 LEGACY devices will always only support FAST mode. 345 </details> 346 <tag id="V1" /> 347 </entry> 348 </static> 349 </section> 350 <section name="control"> 351 <controls> 352 <entry name="aeAntibandingMode" type="byte" visibility="public" 353 enum="true" hwlevel="legacy"> 354 <enum> 355 <value>OFF 356 <notes> 357 The camera device will not adjust exposure duration to 358 avoid banding problems. 359 </notes> 360 </value> 361 <value>50HZ 362 <notes> 363 The camera device will adjust exposure duration to 364 avoid banding problems with 50Hz illumination sources. 365 </notes> 366 </value> 367 <value>60HZ 368 <notes> 369 The camera device will adjust exposure duration to 370 avoid banding problems with 60Hz illumination 371 sources. 372 </notes> 373 </value> 374 <value>AUTO 375 <notes> 376 The camera device will automatically adapt its 377 antibanding routine to the current illumination 378 condition. This is the default mode if AUTO is 379 available on given camera device. 380 </notes> 381 </value> 382 </enum> 383 <description> 384 The desired setting for the camera device's auto-exposure 385 algorithm's antibanding compensation. 386 </description> 387 <range> 388 android.control.aeAvailableAntibandingModes 389 </range> 390 <details> 391 Some kinds of lighting fixtures, such as some fluorescent 392 lights, flicker at the rate of the power supply frequency 393 (60Hz or 50Hz, depending on country). While this is 394 typically not noticeable to a person, it can be visible to 395 a camera device. If a camera sets its exposure time to the 396 wrong value, the flicker may become visible in the 397 viewfinder as flicker or in a final captured image, as a 398 set of variable-brightness bands across the image. 399 400 Therefore, the auto-exposure routines of camera devices 401 include antibanding routines that ensure that the chosen 402 exposure value will not cause such banding. The choice of 403 exposure time depends on the rate of flicker, which the 404 camera device can detect automatically, or the expected 405 rate can be selected by the application using this 406 control. 407 408 A given camera device may not support all of the possible 409 options for the antibanding mode. The 410 android.control.aeAvailableAntibandingModes key contains 411 the available modes for a given camera device. 412 413 AUTO mode is the default if it is available on given 414 camera device. When AUTO mode is not available, the 415 default will be either 50HZ or 60HZ, and both 50HZ 416 and 60HZ will be available. 417 418 If manual exposure control is enabled (by setting 419 android.control.aeMode or android.control.mode to OFF), 420 then this setting has no effect, and the application must 421 ensure it selects exposure times that do not cause banding 422 issues. The android.statistics.sceneFlicker key can assist 423 the application in this. 424 </details> 425 <hal_details> 426 For all capture request templates, this field must be set 427 to AUTO if AUTO mode is available. If AUTO is not available, 428 the default must be either 50HZ or 60HZ, and both 50HZ and 429 60HZ must be available. 430 431 If manual exposure control is enabled (by setting 432 android.control.aeMode or android.control.mode to OFF), 433 then the exposure values provided by the application must not be 434 adjusted for antibanding. 435 </hal_details> 436 <tag id="BC" /> 437 </entry> 438 <entry name="aeExposureCompensation" type="int32" visibility="public" hwlevel="legacy"> 439 <description>Adjustment to auto-exposure (AE) target image 440 brightness.</description> 441 <units>Compensation steps</units> 442 <range>android.control.aeCompensationRange</range> 443 <details> 444 The adjustment is measured as a count of steps, with the 445 step size defined by android.control.aeCompensationStep and the 446 allowed range by android.control.aeCompensationRange. 447 448 For example, if the exposure value (EV) step is 0.333, '6' 449 will mean an exposure compensation of +2 EV; -3 will mean an 450 exposure compensation of -1 EV. One EV represents a doubling 451 of image brightness. Note that this control will only be 452 effective if android.control.aeMode `!=` OFF. This control 453 will take effect even when android.control.aeLock `== true`. 454 455 In the event of exposure compensation value being changed, camera device 456 may take several frames to reach the newly requested exposure target. 457 During that time, android.control.aeState field will be in the SEARCHING 458 state. Once the new exposure target is reached, android.control.aeState will 459 change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or 460 FLASH_REQUIRED (if the scene is too dark for still capture). 461 </details> 462 <tag id="BC" /> 463 </entry> 464 <entry name="aeLock" type="byte" visibility="public" enum="true" 465 typedef="boolean" hwlevel="legacy"> 466 <enum> 467 <value>OFF 468 <notes>Auto-exposure lock is disabled; the AE algorithm 469 is free to update its parameters.</notes></value> 470 <value>ON 471 <notes>Auto-exposure lock is enabled; the AE algorithm 472 must not update the exposure and sensitivity parameters 473 while the lock is active. 474 475 android.control.aeExposureCompensation setting changes 476 will still take effect while auto-exposure is locked. 477 478 Some rare LEGACY devices may not support 479 this, in which case the value will always be overridden to OFF. 480 </notes></value> 481 </enum> 482 <description>Whether auto-exposure (AE) is currently locked to its latest 483 calculated values.</description> 484 <details> 485 When set to `true` (ON), the AE algorithm is locked to its latest parameters, 486 and will not change exposure settings until the lock is set to `false` (OFF). 487 488 Note that even when AE is locked, the flash may be fired if 489 the android.control.aeMode is ON_AUTO_FLASH / 490 ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE. 491 492 When android.control.aeExposureCompensation is changed, even if the AE lock 493 is ON, the camera device will still adjust its exposure value. 494 495 If AE precapture is triggered (see android.control.aePrecaptureTrigger) 496 when AE is already locked, the camera device will not change the exposure time 497 (android.sensor.exposureTime) and sensitivity (android.sensor.sensitivity) 498 parameters. The flash may be fired if the android.control.aeMode 499 is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the 500 android.control.aeMode is ON_ALWAYS_FLASH, the scene may become overexposed. 501 502 Since the camera device has a pipeline of in-flight requests, the settings that 503 get locked do not necessarily correspond to the settings that were present in the 504 latest capture result received from the camera device, since additional captures 505 and AE updates may have occurred even before the result was sent out. If an 506 application is switching between automatic and manual control and wishes to eliminate 507 any flicker during the switch, the following procedure is recommended: 508 509 1. Starting in auto-AE mode: 510 2. Lock AE 511 3. Wait for the first result to be output that has the AE locked 512 4. Copy exposure settings from that result into a request, set the request to manual AE 513 5. Submit the capture request, proceed to run manual AE as desired. 514 515 See android.control.aeState for AE lock related state transition details. 516 </details> 517 <tag id="BC" /> 518 </entry> 519 <entry name="aeMode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 520 <enum> 521 <value>OFF 522 <notes> 523 The camera device's autoexposure routine is disabled. 524 525 The application-selected android.sensor.exposureTime, 526 android.sensor.sensitivity and 527 android.sensor.frameDuration are used by the camera 528 device, along with android.flash.* fields, if there's 529 a flash unit for this camera device. 530 531 Note that auto-white balance (AWB) and auto-focus (AF) 532 behavior is device dependent when AE is in OFF mode. 533 To have consistent behavior across different devices, 534 it is recommended to either set AWB and AF to OFF mode 535 or lock AWB and AF before setting AE to OFF. 536 See android.control.awbMode, android.control.afMode, 537 android.control.awbLock, and android.control.afTrigger 538 for more details. 539 540 LEGACY devices do not support the OFF mode and will 541 override attempts to use this value to ON. 542 </notes> 543 </value> 544 <value>ON 545 <notes> 546 The camera device's autoexposure routine is active, 547 with no flash control. 548 549 The application's values for 550 android.sensor.exposureTime, 551 android.sensor.sensitivity, and 552 android.sensor.frameDuration are ignored. The 553 application has control over the various 554 android.flash.* fields. 555 </notes> 556 </value> 557 <value>ON_AUTO_FLASH 558 <notes> 559 Like ON, except that the camera device also controls 560 the camera's flash unit, firing it in low-light 561 conditions. 562 563 The flash may be fired during a precapture sequence 564 (triggered by android.control.aePrecaptureTrigger) and 565 may be fired for captures for which the 566 android.control.captureIntent field is set to 567 STILL_CAPTURE 568 </notes> 569 </value> 570 <value>ON_ALWAYS_FLASH 571 <notes> 572 Like ON, except that the camera device also controls 573 the camera's flash unit, always firing it for still 574 captures. 575 576 The flash may be fired during a precapture sequence 577 (triggered by android.control.aePrecaptureTrigger) and 578 will always be fired for captures for which the 579 android.control.captureIntent field is set to 580 STILL_CAPTURE 581 </notes> 582 </value> 583 <value>ON_AUTO_FLASH_REDEYE 584 <notes> 585 Like ON_AUTO_FLASH, but with automatic red eye 586 reduction. 587 588 If deemed necessary by the camera device, a red eye 589 reduction flash will fire during the precapture 590 sequence. 591 </notes> 592 </value> 593 </enum> 594 <description>The desired mode for the camera device's 595 auto-exposure routine.</description> 596 <range>android.control.aeAvailableModes</range> 597 <details> 598 This control is only effective if android.control.mode is 599 AUTO. 600 601 When set to any of the ON modes, the camera device's 602 auto-exposure routine is enabled, overriding the 603 application's selected exposure time, sensor sensitivity, 604 and frame duration (android.sensor.exposureTime, 605 android.sensor.sensitivity, and 606 android.sensor.frameDuration). If one of the FLASH modes 607 is selected, the camera device's flash unit controls are 608 also overridden. 609 610 The FLASH modes are only available if the camera device 611 has a flash unit (android.flash.info.available is `true`). 612 613 If flash TORCH mode is desired, this field must be set to 614 ON or OFF, and android.flash.mode set to TORCH. 615 616 When set to any of the ON modes, the values chosen by the 617 camera device auto-exposure routine for the overridden 618 fields for a given capture will be available in its 619 CaptureResult. 620 </details> 621 <tag id="BC" /> 622 </entry> 623 <entry name="aeRegions" type="int32" visibility="public" 624 optional="true" container="array" typedef="meteringRectangle"> 625 <array> 626 <size>5</size> 627 <size>area_count</size> 628 </array> 629 <description>List of metering areas to use for auto-exposure adjustment.</description> 630 <units>Pixel coordinates within android.sensor.info.activeArraySize</units> 631 <range>Coordinates must be between `[(0,0), (width, height))` of 632 android.sensor.info.activeArraySize</range> 633 <details> 634 Not available if android.control.maxRegionsAe is 0. 635 Otherwise will always be present. 636 637 The maximum number of regions supported by the device is determined by the value 638 of android.control.maxRegionsAe. 639 640 The coordinate system is based on the active pixel array, 641 with (0,0) being the top-left pixel in the active pixel array, and 642 (android.sensor.info.activeArraySize.width - 1, 643 android.sensor.info.activeArraySize.height - 1) being the 644 bottom-right pixel in the active pixel array. 645 646 The weight must be within `[0, 1000]`, and represents a weight 647 for every pixel in the area. This means that a large metering area 648 with the same weight as a smaller area will have more effect in 649 the metering result. Metering areas can partially overlap and the 650 camera device will add the weights in the overlap region. 651 652 The weights are relative to weights of other exposure metering regions, so if only one 653 region is used, all non-zero weights will have the same effect. A region with 0 654 weight is ignored. 655 656 If all regions have 0 weight, then no specific metering area needs to be used by the 657 camera device. 658 659 If the metering region is outside the used android.scaler.cropRegion returned in 660 capture result metadata, the camera device will ignore the sections outside the crop 661 region and output only the intersection rectangle as the metering region in the result 662 metadata. If the region is entirely outside the crop region, it will be ignored and 663 not reported in the result metadata. 664 </details> 665 <hal_details> 666 The HAL level representation of MeteringRectangle[] is a 667 int[5 * area_count]. 668 Every five elements represent a metering region of 669 (xmin, ymin, xmax, ymax, weight). 670 The rectangle is defined to be inclusive on xmin and ymin, but 671 exclusive on xmax and ymax. 672 </hal_details> 673 <tag id="BC" /> 674 </entry> 675 <entry name="aeTargetFpsRange" type="int32" visibility="public" 676 container="array" typedef="rangeInt" hwlevel="legacy"> 677 <array> 678 <size>2</size> 679 </array> 680 <description>Range over which the auto-exposure routine can 681 adjust the capture frame rate to maintain good 682 exposure.</description> 683 <units>Frames per second (FPS)</units> 684 <range>Any of the entries in android.control.aeAvailableTargetFpsRanges</range> 685 <details>Only constrains auto-exposure (AE) algorithm, not 686 manual control of android.sensor.exposureTime and 687 android.sensor.frameDuration.</details> 688 <tag id="BC" /> 689 </entry> 690 <entry name="aePrecaptureTrigger" type="byte" visibility="public" 691 enum="true" hwlevel="limited"> 692 <enum> 693 <value>IDLE 694 <notes>The trigger is idle.</notes> 695 </value> 696 <value>START 697 <notes>The precapture metering sequence will be started 698 by the camera device. 699 700 The exact effect of the precapture trigger depends on 701 the current AE mode and state.</notes> 702 </value> 703 </enum> 704 <description>Whether the camera device will trigger a precapture 705 metering sequence when it processes this request.</description> 706 <details>This entry is normally set to IDLE, or is not 707 included at all in the request settings. When included and 708 set to START, the camera device will trigger the auto-exposure (AE) 709 precapture metering sequence. 710 711 The precapture sequence should be triggered before starting a 712 high-quality still capture for final metering decisions to 713 be made, and for firing pre-capture flash pulses to estimate 714 scene brightness and required final capture flash power, when 715 the flash is enabled. 716 717 Normally, this entry should be set to START for only a 718 single request, and the application should wait until the 719 sequence completes before starting a new one. 720 721 When a precapture metering sequence is finished, the camera device 722 may lock the auto-exposure routine internally to be able to accurately expose the 723 subsequent still capture image (`android.control.captureIntent == STILL_CAPTURE`). 724 For this case, the AE may not resume normal scan if no subsequent still capture is 725 submitted. To ensure that the AE routine restarts normal scan, the application should 726 submit a request with `android.control.aeLock == true`, followed by a request 727 with `android.control.aeLock == false`, if the application decides not to submit a 728 still capture request after the precapture sequence completes. 729 730 The exact effect of auto-exposure (AE) precapture trigger 731 depends on the current AE mode and state; see 732 android.control.aeState for AE precapture state transition 733 details. 734 735 On LEGACY-level devices, the precapture trigger is not supported; 736 capturing a high-resolution JPEG image will automatically trigger a 737 precapture sequence before the high-resolution capture, including 738 potentially firing a pre-capture flash. 739 </details> 740 <tag id="BC" /> 741 </entry> 742 <entry name="afMode" type="byte" visibility="public" enum="true" 743 hwlevel="legacy"> 744 <enum> 745 <value>OFF 746 <notes>The auto-focus routine does not control the lens; 747 android.lens.focusDistance is controlled by the 748 application.</notes></value> 749 <value>AUTO 750 <notes>Basic automatic focus mode. 751 752 In this mode, the lens does not move unless 753 the autofocus trigger action is called. When that trigger 754 is activated, AF will transition to ACTIVE_SCAN, then to 755 the outcome of the scan (FOCUSED or NOT_FOCUSED). 756 757 Always supported if lens is not fixed focus. 758 759 Use android.lens.info.minimumFocusDistance to determine if lens 760 is fixed-focus. 761 762 Triggering AF_CANCEL resets the lens position to default, 763 and sets the AF state to INACTIVE.</notes></value> 764 <value>MACRO 765 <notes>Close-up focusing mode. 766 767 In this mode, the lens does not move unless the 768 autofocus trigger action is called. When that trigger is 769 activated, AF will transition to ACTIVE_SCAN, then to 770 the outcome of the scan (FOCUSED or NOT_FOCUSED). This 771 mode is optimized for focusing on objects very close to 772 the camera. 773 774 When that trigger is activated, AF will transition to 775 ACTIVE_SCAN, then to the outcome of the scan (FOCUSED or 776 NOT_FOCUSED). Triggering cancel AF resets the lens 777 position to default, and sets the AF state to 778 INACTIVE.</notes></value> 779 <value>CONTINUOUS_VIDEO 780 <notes>In this mode, the AF algorithm modifies the lens 781 position continually to attempt to provide a 782 constantly-in-focus image stream. 783 784 The focusing behavior should be suitable for good quality 785 video recording; typically this means slower focus 786 movement and no overshoots. When the AF trigger is not 787 involved, the AF algorithm should start in INACTIVE state, 788 and then transition into PASSIVE_SCAN and PASSIVE_FOCUSED 789 states as appropriate. When the AF trigger is activated, 790 the algorithm should immediately transition into 791 AF_FOCUSED or AF_NOT_FOCUSED as appropriate, and lock the 792 lens position until a cancel AF trigger is received. 793 794 Once cancel is received, the algorithm should transition 795 back to INACTIVE and resume passive scan. Note that this 796 behavior is not identical to CONTINUOUS_PICTURE, since an 797 ongoing PASSIVE_SCAN must immediately be 798 canceled.</notes></value> 799 <value>CONTINUOUS_PICTURE 800 <notes>In this mode, the AF algorithm modifies the lens 801 position continually to attempt to provide a 802 constantly-in-focus image stream. 803 804 The focusing behavior should be suitable for still image 805 capture; typically this means focusing as fast as 806 possible. When the AF trigger is not involved, the AF 807 algorithm should start in INACTIVE state, and then 808 transition into PASSIVE_SCAN and PASSIVE_FOCUSED states as 809 appropriate as it attempts to maintain focus. When the AF 810 trigger is activated, the algorithm should finish its 811 PASSIVE_SCAN if active, and then transition into 812 AF_FOCUSED or AF_NOT_FOCUSED as appropriate, and lock the 813 lens position until a cancel AF trigger is received. 814 815 When the AF cancel trigger is activated, the algorithm 816 should transition back to INACTIVE and then act as if it 817 has just been started.</notes></value> 818 <value>EDOF 819 <notes>Extended depth of field (digital focus) mode. 820 821 The camera device will produce images with an extended 822 depth of field automatically; no special focusing 823 operations need to be done before taking a picture. 824 825 AF triggers are ignored, and the AF state will always be 826 INACTIVE.</notes></value> 827 </enum> 828 <description>Whether auto-focus (AF) is currently enabled, and what 829 mode it is set to.</description> 830 <range>android.control.afAvailableModes</range> 831 <details>Only effective if android.control.mode = AUTO and the lens is not fixed focus 832 (i.e. `android.lens.info.minimumFocusDistance > 0`). Also note that 833 when android.control.aeMode is OFF, the behavior of AF is device 834 dependent. It is recommended to lock AF by using android.control.afTrigger before 835 setting android.control.aeMode to OFF, or set AF mode to OFF when AE is OFF. 836 837 If the lens is controlled by the camera device auto-focus algorithm, 838 the camera device will report the current AF status in android.control.afState 839 in result metadata.</details> 840 <hal_details> 841 When afMode is AUTO or MACRO, the lens must not move until an AF trigger is sent in a 842 request (android.control.afTrigger `==` START). After an AF trigger, the afState will end 843 up with either FOCUSED_LOCKED or NOT_FOCUSED_LOCKED state (see 844 android.control.afState for detailed state transitions), which indicates that the lens is 845 locked and will not move. If camera movement (e.g. tilting camera) causes the lens to move 846 after the lens is locked, the HAL must compensate this movement appropriately such that 847 the same focal plane remains in focus. 848 849 When afMode is one of the continuous auto focus modes, the HAL is free to start a AF 850 scan whenever it's not locked. When the lens is locked after an AF trigger 851 (see android.control.afState for detailed state transitions), the HAL should maintain the 852 same lock behavior as above. 853 854 When afMode is OFF, the application controls focus manually. The accuracy of the 855 focus distance control depends on the android.lens.info.focusDistanceCalibration. 856 However, the lens must not move regardless of the camera movement for any focus distance 857 manual control. 858 859 To put this in concrete terms, if the camera has lens elements which may move based on 860 camera orientation or motion (e.g. due to gravity), then the HAL must drive the lens to 861 remain in a fixed position invariant to the camera's orientation or motion, for example, 862 by using accelerometer measurements in the lens control logic. This is a typical issue 863 that will arise on camera modules with open-loop VCMs. 864 </hal_details> 865 <tag id="BC" /> 866 </entry> 867 <entry name="afRegions" type="int32" visibility="public" 868 optional="true" container="array" typedef="meteringRectangle"> 869 <array> 870 <size>5</size> 871 <size>area_count</size> 872 </array> 873 <description>List of metering areas to use for auto-focus.</description> 874 <units>Pixel coordinates within android.sensor.info.activeArraySize</units> 875 <range>Coordinates must be between `[(0,0), (width, height))` of 876 android.sensor.info.activeArraySize</range> 877 <details> 878 Not available if android.control.maxRegionsAf is 0. 879 Otherwise will always be present. 880 881 The maximum number of focus areas supported by the device is determined by the value 882 of android.control.maxRegionsAf. 883 884 The coordinate system is based on the active pixel array, 885 with (0,0) being the top-left pixel in the active pixel array, and 886 (android.sensor.info.activeArraySize.width - 1, 887 android.sensor.info.activeArraySize.height - 1) being the 888 bottom-right pixel in the active pixel array. 889 890 The weight must be within `[0, 1000]`, and represents a weight 891 for every pixel in the area. This means that a large metering area 892 with the same weight as a smaller area will have more effect in 893 the metering result. Metering areas can partially overlap and the 894 camera device will add the weights in the overlap region. 895 896 The weights are relative to weights of other metering regions, so if only one region 897 is used, all non-zero weights will have the same effect. A region with 0 weight is 898 ignored. 899 900 If all regions have 0 weight, then no specific metering area needs to be used by the 901 camera device. 902 903 If the metering region is outside the used android.scaler.cropRegion returned in 904 capture result metadata, the camera device will ignore the sections outside the crop 905 region and output only the intersection rectangle as the metering region in the result 906 metadata. If the region is entirely outside the crop region, it will be ignored and 907 not reported in the result metadata. 908 </details> 909 <hal_details> 910 The HAL level representation of MeteringRectangle[] is a 911 int[5 * area_count]. 912 Every five elements represent a metering region of 913 (xmin, ymin, xmax, ymax, weight). 914 The rectangle is defined to be inclusive on xmin and ymin, but 915 exclusive on xmax and ymax. 916 </hal_details> 917 <tag id="BC" /> 918 </entry> 919 <entry name="afTrigger" type="byte" visibility="public" enum="true" 920 hwlevel="legacy"> 921 <enum> 922 <value>IDLE 923 <notes>The trigger is idle.</notes> 924 </value> 925 <value>START 926 <notes>Autofocus will trigger now.</notes> 927 </value> 928 <value>CANCEL 929 <notes>Autofocus will return to its initial 930 state, and cancel any currently active trigger.</notes> 931 </value> 932 </enum> 933 <description> 934 Whether the camera device will trigger autofocus for this request. 935 </description> 936 <details>This entry is normally set to IDLE, or is not 937 included at all in the request settings. 938 939 When included and set to START, the camera device will trigger the 940 autofocus algorithm. If autofocus is disabled, this trigger has no effect. 941 942 When set to CANCEL, the camera device will cancel any active trigger, 943 and return to its initial AF state. 944 945 Generally, applications should set this entry to START or CANCEL for only a 946 single capture, and then return it to IDLE (or not set at all). Specifying 947 START for multiple captures in a row means restarting the AF operation over 948 and over again. 949 950 See android.control.afState for what the trigger means for each AF mode. 951 </details> 952 <tag id="BC" /> 953 </entry> 954 <entry name="awbLock" type="byte" visibility="public" enum="true" 955 typedef="boolean" hwlevel="legacy"> 956 <enum> 957 <value>OFF 958 <notes>Auto-white balance lock is disabled; the AWB 959 algorithm is free to update its parameters if in AUTO 960 mode.</notes></value> 961 <value>ON 962 <notes>Auto-white balance lock is enabled; the AWB 963 algorithm will not update its parameters while the lock 964 is active.</notes></value> 965 </enum> 966 <description>Whether auto-white balance (AWB) is currently locked to its 967 latest calculated values.</description> 968 <details> 969 When set to `true` (ON), the AWB algorithm is locked to its latest parameters, 970 and will not change color balance settings until the lock is set to `false` (OFF). 971 972 Since the camera device has a pipeline of in-flight requests, the settings that 973 get locked do not necessarily correspond to the settings that were present in the 974 latest capture result received from the camera device, since additional captures 975 and AWB updates may have occurred even before the result was sent out. If an 976 application is switching between automatic and manual control and wishes to eliminate 977 any flicker during the switch, the following procedure is recommended: 978 979 1. Starting in auto-AWB mode: 980 2. Lock AWB 981 3. Wait for the first result to be output that has the AWB locked 982 4. Copy AWB settings from that result into a request, set the request to manual AWB 983 5. Submit the capture request, proceed to run manual AWB as desired. 984 985 Note that AWB lock is only meaningful when 986 android.control.awbMode is in the AUTO mode; in other modes, 987 AWB is already fixed to a specific setting. 988 989 Some LEGACY devices may not support ON; the value is then overridden to OFF. 990 </details> 991 <tag id="BC" /> 992 </entry> 993 <entry name="awbMode" type="byte" visibility="public" enum="true" 994 hwlevel="legacy"> 995 <enum> 996 <value>OFF 997 <notes> 998 The camera device's auto-white balance routine is disabled. 999 1000 The application-selected color transform matrix 1001 (android.colorCorrection.transform) and gains 1002 (android.colorCorrection.gains) are used by the camera 1003 device for manual white balance control. 1004 </notes> 1005 </value> 1006 <value>AUTO 1007 <notes> 1008 The camera device's auto-white balance routine is active. 1009 1010 The application's values for android.colorCorrection.transform 1011 and android.colorCorrection.gains are ignored. 1012 For devices that support the MANUAL_POST_PROCESSING capability, the 1013 values used by the camera device for the transform and gains 1014 will be available in the capture result for this request. 1015 </notes> 1016 </value> 1017 <value>INCANDESCENT 1018 <notes> 1019 The camera device's auto-white balance routine is disabled; 1020 the camera device uses incandescent light as the assumed scene 1021 illumination for white balance. 1022 1023 While the exact white balance transforms are up to the 1024 camera device, they will approximately match the CIE 1025 standard illuminant A. 1026 1027 The application's values for android.colorCorrection.transform 1028 and android.colorCorrection.gains are ignored. 1029 For devices that support the MANUAL_POST_PROCESSING capability, the 1030 values used by the camera device for the transform and gains 1031 will be available in the capture result for this request. 1032 </notes> 1033 </value> 1034 <value>FLUORESCENT 1035 <notes> 1036 The camera device's auto-white balance routine is disabled; 1037 the camera device uses fluorescent light as the assumed scene 1038 illumination for white balance. 1039 1040 While the exact white balance transforms are up to the 1041 camera device, they will approximately match the CIE 1042 standard illuminant F2. 1043 1044 The application's values for android.colorCorrection.transform 1045 and android.colorCorrection.gains are ignored. 1046 For devices that support the MANUAL_POST_PROCESSING capability, the 1047 values used by the camera device for the transform and gains 1048 will be available in the capture result for this request. 1049 </notes> 1050 </value> 1051 <value>WARM_FLUORESCENT 1052 <notes> 1053 The camera device's auto-white balance routine is disabled; 1054 the camera device uses warm fluorescent light as the assumed scene 1055 illumination for white balance. 1056 1057 While the exact white balance transforms are up to the 1058 camera device, they will approximately match the CIE 1059 standard illuminant F4. 1060 1061 The application's values for android.colorCorrection.transform 1062 and android.colorCorrection.gains are ignored. 1063 For devices that support the MANUAL_POST_PROCESSING capability, the 1064 values used by the camera device for the transform and gains 1065 will be available in the capture result for this request. 1066 </notes> 1067 </value> 1068 <value>DAYLIGHT 1069 <notes> 1070 The camera device's auto-white balance routine is disabled; 1071 the camera device uses daylight light as the assumed scene 1072 illumination for white balance. 1073 1074 While the exact white balance transforms are up to the 1075 camera device, they will approximately match the CIE 1076 standard illuminant D65. 1077 1078 The application's values for android.colorCorrection.transform 1079 and android.colorCorrection.gains are ignored. 1080 For devices that support the MANUAL_POST_PROCESSING capability, the 1081 values used by the camera device for the transform and gains 1082 will be available in the capture result for this request. 1083 </notes> 1084 </value> 1085 <value>CLOUDY_DAYLIGHT 1086 <notes> 1087 The camera device's auto-white balance routine is disabled; 1088 the camera device uses cloudy daylight light as the assumed scene 1089 illumination for white balance. 1090 1091 The application's values for android.colorCorrection.transform 1092 and android.colorCorrection.gains are ignored. 1093 For devices that support the MANUAL_POST_PROCESSING capability, the 1094 values used by the camera device for the transform and gains 1095 will be available in the capture result for this request. 1096 </notes> 1097 </value> 1098 <value>TWILIGHT 1099 <notes> 1100 The camera device's auto-white balance routine is disabled; 1101 the camera device uses twilight light as the assumed scene 1102 illumination for white balance. 1103 1104 The application's values for android.colorCorrection.transform 1105 and android.colorCorrection.gains are ignored. 1106 For devices that support the MANUAL_POST_PROCESSING capability, the 1107 values used by the camera device for the transform and gains 1108 will be available in the capture result for this request. 1109 </notes> 1110 </value> 1111 <value>SHADE 1112 <notes> 1113 The camera device's auto-white balance routine is disabled; 1114 the camera device uses shade light as the assumed scene 1115 illumination for white balance. 1116 1117 The application's values for android.colorCorrection.transform 1118 and android.colorCorrection.gains are ignored. 1119 For devices that support the MANUAL_POST_PROCESSING capability, the 1120 values used by the camera device for the transform and gains 1121 will be available in the capture result for this request. 1122 </notes> 1123 </value> 1124 </enum> 1125 <description>Whether auto-white balance (AWB) is currently setting the color 1126 transform fields, and what its illumination target 1127 is.</description> 1128 <range>android.control.awbAvailableModes</range> 1129 <details> 1130 This control is only effective if android.control.mode is AUTO. 1131 1132 When set to the ON mode, the camera device's auto-white balance 1133 routine is enabled, overriding the application's selected 1134 android.colorCorrection.transform, android.colorCorrection.gains and 1135 android.colorCorrection.mode. Note that when android.control.aeMode 1136 is OFF, the behavior of AWB is device dependent. It is recommened to 1137 also set AWB mode to OFF or lock AWB by using android.control.awbLock before 1138 setting AE mode to OFF. 1139 1140 When set to the OFF mode, the camera device's auto-white balance 1141 routine is disabled. The application manually controls the white 1142 balance by android.colorCorrection.transform, android.colorCorrection.gains 1143 and android.colorCorrection.mode. 1144 1145 When set to any other modes, the camera device's auto-white 1146 balance routine is disabled. The camera device uses each 1147 particular illumination target for white balance 1148 adjustment. The application's values for 1149 android.colorCorrection.transform, 1150 android.colorCorrection.gains and 1151 android.colorCorrection.mode are ignored. 1152 </details> 1153 <tag id="BC" /> 1154 </entry> 1155 <entry name="awbRegions" type="int32" visibility="public" 1156 optional="true" container="array" typedef="meteringRectangle"> 1157 <array> 1158 <size>5</size> 1159 <size>area_count</size> 1160 </array> 1161 <description>List of metering areas to use for auto-white-balance illuminant 1162 estimation.</description> 1163 <units>Pixel coordinates within android.sensor.info.activeArraySize</units> 1164 <range>Coordinates must be between `[(0,0), (width, height))` of 1165 android.sensor.info.activeArraySize</range> 1166 <details> 1167 Not available if android.control.maxRegionsAwb is 0. 1168 Otherwise will always be present. 1169 1170 The maximum number of regions supported by the device is determined by the value 1171 of android.control.maxRegionsAwb. 1172 1173 The coordinate system is based on the active pixel array, 1174 with (0,0) being the top-left pixel in the active pixel array, and 1175 (android.sensor.info.activeArraySize.width - 1, 1176 android.sensor.info.activeArraySize.height - 1) being the 1177 bottom-right pixel in the active pixel array. 1178 1179 The weight must range from 0 to 1000, and represents a weight 1180 for every pixel in the area. This means that a large metering area 1181 with the same weight as a smaller area will have more effect in 1182 the metering result. Metering areas can partially overlap and the 1183 camera device will add the weights in the overlap region. 1184 1185 The weights are relative to weights of other white balance metering regions, so if 1186 only one region is used, all non-zero weights will have the same effect. A region with 1187 0 weight is ignored. 1188 1189 If all regions have 0 weight, then no specific metering area needs to be used by the 1190 camera device. 1191 1192 If the metering region is outside the used android.scaler.cropRegion returned in 1193 capture result metadata, the camera device will ignore the sections outside the crop 1194 region and output only the intersection rectangle as the metering region in the result 1195 metadata. If the region is entirely outside the crop region, it will be ignored and 1196 not reported in the result metadata. 1197 </details> 1198 <hal_details> 1199 The HAL level representation of MeteringRectangle[] is a 1200 int[5 * area_count]. 1201 Every five elements represent a metering region of 1202 (xmin, ymin, xmax, ymax, weight). 1203 The rectangle is defined to be inclusive on xmin and ymin, but 1204 exclusive on xmax and ymax. 1205 </hal_details> 1206 <tag id="BC" /> 1207 </entry> 1208 <entry name="captureIntent" type="byte" visibility="public" enum="true" 1209 hwlevel="legacy"> 1210 <enum> 1211 <value>CUSTOM 1212 <notes>The goal of this request doesn't fall into the other 1213 categories. The camera device will default to preview-like 1214 behavior.</notes></value> 1215 <value>PREVIEW 1216 <notes>This request is for a preview-like use case. 1217 1218 The precapture trigger may be used to start off a metering 1219 w/flash sequence. 1220 </notes></value> 1221 <value>STILL_CAPTURE 1222 <notes>This request is for a still capture-type 1223 use case. 1224 1225 If the flash unit is under automatic control, it may fire as needed. 1226 </notes></value> 1227 <value>VIDEO_RECORD 1228 <notes>This request is for a video recording 1229 use case.</notes></value> 1230 <value>VIDEO_SNAPSHOT 1231 <notes>This request is for a video snapshot (still 1232 image while recording video) use case. 1233 1234 The camera device should take the highest-quality image 1235 possible (given the other settings) without disrupting the 1236 frame rate of video recording. </notes></value> 1237 <value>ZERO_SHUTTER_LAG 1238 <notes>This request is for a ZSL usecase; the 1239 application will stream full-resolution images and 1240 reprocess one or several later for a final 1241 capture. 1242 </notes></value> 1243 <value>MANUAL 1244 <notes>This request is for manual capture use case where 1245 the applications want to directly control the capture parameters. 1246 1247 For example, the application may wish to manually control 1248 android.sensor.exposureTime, android.sensor.sensitivity, etc. 1249 </notes></value> 1250 </enum> 1251 <description>Information to the camera device 3A (auto-exposure, 1252 auto-focus, auto-white balance) routines about the purpose 1253 of this capture, to help the camera device to decide optimal 3A 1254 strategy.</description> 1255 <details>This control (except for MANUAL) is only effective if 1256 `android.control.mode != OFF` and any 3A routine is active. 1257 1258 ZERO_SHUTTER_LAG will be supported if android.request.availableCapabilities 1259 contains ZSL. MANUAL will be supported if android.request.availableCapabilities 1260 contains MANUAL_SENSOR. Other intent values are always supported. 1261 </details> 1262 <tag id="BC" /> 1263 </entry> 1264 <entry name="effectMode" type="byte" visibility="public" enum="true" 1265 hwlevel="legacy"> 1266 <enum> 1267 <value>OFF 1268 <notes> 1269 No color effect will be applied. 1270 </notes> 1271 </value> 1272 <value optional="true">MONO 1273 <notes> 1274 A "monocolor" effect where the image is mapped into 1275 a single color. 1276 1277 This will typically be grayscale. 1278 </notes> 1279 </value> 1280 <value optional="true">NEGATIVE 1281 <notes> 1282 A "photo-negative" effect where the image's colors 1283 are inverted. 1284 </notes> 1285 </value> 1286 <value optional="true">SOLARIZE 1287 <notes> 1288 A "solarisation" effect (Sabattier effect) where the 1289 image is wholly or partially reversed in 1290 tone. 1291 </notes> 1292 </value> 1293 <value optional="true">SEPIA 1294 <notes> 1295 A "sepia" effect where the image is mapped into warm 1296 gray, red, and brown tones. 1297 </notes> 1298 </value> 1299 <value optional="true">POSTERIZE 1300 <notes> 1301 A "posterization" effect where the image uses 1302 discrete regions of tone rather than a continuous 1303 gradient of tones. 1304 </notes> 1305 </value> 1306 <value optional="true">WHITEBOARD 1307 <notes> 1308 A "whiteboard" effect where the image is typically displayed 1309 as regions of white, with black or grey details. 1310 </notes> 1311 </value> 1312 <value optional="true">BLACKBOARD 1313 <notes> 1314 A "blackboard" effect where the image is typically displayed 1315 as regions of black, with white or grey details. 1316 </notes> 1317 </value> 1318 <value optional="true">AQUA 1319 <notes> 1320 An "aqua" effect where a blue hue is added to the image. 1321 </notes> 1322 </value> 1323 </enum> 1324 <description>A special color effect to apply.</description> 1325 <range>android.control.availableEffects</range> 1326 <details> 1327 When this mode is set, a color effect will be applied 1328 to images produced by the camera device. The interpretation 1329 and implementation of these color effects is left to the 1330 implementor of the camera device, and should not be 1331 depended on to be consistent (or present) across all 1332 devices. 1333 </details> 1334 <tag id="BC" /> 1335 </entry> 1336 <entry name="mode" type="byte" visibility="public" enum="true" 1337 hwlevel="legacy"> 1338 <enum> 1339 <value>OFF 1340 <notes>Full application control of pipeline. 1341 1342 All control by the device's metering and focusing (3A) 1343 routines is disabled, and no other settings in 1344 android.control.* have any effect, except that 1345 android.control.captureIntent may be used by the camera 1346 device to select post-processing values for processing 1347 blocks that do not allow for manual control, or are not 1348 exposed by the camera API. 1349 1350 However, the camera device's 3A routines may continue to 1351 collect statistics and update their internal state so that 1352 when control is switched to AUTO mode, good control values 1353 can be immediately applied. 1354 </notes></value> 1355 <value>AUTO 1356 <notes>Use settings for each individual 3A routine. 1357 1358 Manual control of capture parameters is disabled. All 1359 controls in android.control.* besides sceneMode take 1360 effect.</notes></value> 1361 <value>USE_SCENE_MODE 1362 <notes>Use a specific scene mode. 1363 1364 Enabling this disables control.aeMode, control.awbMode and 1365 control.afMode controls; the camera device will ignore 1366 those settings while USE_SCENE_MODE is active (except for 1367 FACE_PRIORITY scene mode). Other control entries are still 1368 active. This setting can only be used if scene mode is 1369 supported (i.e. android.control.availableSceneModes 1370 contain some modes other than DISABLED).</notes></value> 1371 <value>OFF_KEEP_STATE 1372 <notes>Same as OFF mode, except that this capture will not be 1373 used by camera device background auto-exposure, auto-white balance and 1374 auto-focus algorithms (3A) to update their statistics. 1375 1376 Specifically, the 3A routines are locked to the last 1377 values set from a request with AUTO, OFF, or 1378 USE_SCENE_MODE, and any statistics or state updates 1379 collected from manual captures with OFF_KEEP_STATE will be 1380 discarded by the camera device. 1381 </notes></value> 1382 </enum> 1383 <description>Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control 1384 routines.</description> 1385 <details> 1386 This is a top-level 3A control switch. When set to OFF, all 3A control 1387 by the camera device is disabled. The application must set the fields for 1388 capture parameters itself. 1389 1390 When set to AUTO, the individual algorithm controls in 1391 android.control.* are in effect, such as android.control.afMode. 1392 1393 When set to USE_SCENE_MODE, the individual controls in 1394 android.control.* are mostly disabled, and the camera device implements 1395 one of the scene mode settings (such as ACTION, SUNSET, or PARTY) 1396 as it wishes. The camera device scene mode 3A settings are provided by 1397 android.control.sceneModeOverrides. 1398 1399 When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference 1400 is that this frame will not be used by camera device background 3A statistics 1401 update, as if this frame is never captured. This mode can be used in the scenario 1402 where the application doesn't want a 3A manual control capture to affect 1403 the subsequent auto 3A capture results. 1404 1405 LEGACY mode devices will only support AUTO and USE_SCENE_MODE modes. 1406 LIMITED mode devices will only support OFF and OFF_KEEP_STATE if they 1407 support the MANUAL_SENSOR and MANUAL_POST_PROCSESING capabilities. 1408 FULL mode devices will always support OFF and OFF_KEEP_STATE. 1409 </details> 1410 <tag id="BC" /> 1411 </entry> 1412 <entry name="sceneMode" type="byte" visibility="public" enum="true" 1413 hwlevel="legacy"> 1414 <enum> 1415 <value id="0">DISABLED 1416 <notes> 1417 Indicates that no scene modes are set for a given capture request. 1418 </notes> 1419 </value> 1420 <value>FACE_PRIORITY 1421 <notes>If face detection support exists, use face 1422 detection data for auto-focus, auto-white balance, and 1423 auto-exposure routines. 1424 1425 If face detection statistics are disabled 1426 (i.e. android.statistics.faceDetectMode is set to OFF), 1427 this should still operate correctly (but will not return 1428 face detection statistics to the framework). 1429 1430 Unlike the other scene modes, android.control.aeMode, 1431 android.control.awbMode, and android.control.afMode 1432 remain active when FACE_PRIORITY is set. 1433 </notes> 1434 </value> 1435 <value optional="true">ACTION 1436 <notes> 1437 Optimized for photos of quickly moving objects. 1438 1439 Similar to SPORTS. 1440 </notes> 1441 </value> 1442 <value optional="true">PORTRAIT 1443 <notes> 1444 Optimized for still photos of people. 1445 </notes> 1446 </value> 1447 <value optional="true">LANDSCAPE 1448 <notes> 1449 Optimized for photos of distant macroscopic objects. 1450 </notes> 1451 </value> 1452 <value optional="true">NIGHT 1453 <notes> 1454 Optimized for low-light settings. 1455 </notes> 1456 </value> 1457 <value optional="true">NIGHT_PORTRAIT 1458 <notes> 1459 Optimized for still photos of people in low-light 1460 settings. 1461 </notes> 1462 </value> 1463 <value optional="true">THEATRE 1464 <notes> 1465 Optimized for dim, indoor settings where flash must 1466 remain off. 1467 </notes> 1468 </value> 1469 <value optional="true">BEACH 1470 <notes> 1471 Optimized for bright, outdoor beach settings. 1472 </notes> 1473 </value> 1474 <value optional="true">SNOW 1475 <notes> 1476 Optimized for bright, outdoor settings containing snow. 1477 </notes> 1478 </value> 1479 <value optional="true">SUNSET 1480 <notes> 1481 Optimized for scenes of the setting sun. 1482 </notes> 1483 </value> 1484 <value optional="true">STEADYPHOTO 1485 <notes> 1486 Optimized to avoid blurry photos due to small amounts of 1487 device motion (for example: due to hand shake). 1488 </notes> 1489 </value> 1490 <value optional="true">FIREWORKS 1491 <notes> 1492 Optimized for nighttime photos of fireworks. 1493 </notes> 1494 </value> 1495 <value optional="true">SPORTS 1496 <notes> 1497 Optimized for photos of quickly moving people. 1498 1499 Similar to ACTION. 1500 </notes> 1501 </value> 1502 <value optional="true">PARTY 1503 <notes> 1504 Optimized for dim, indoor settings with multiple moving 1505 people. 1506 </notes> 1507 </value> 1508 <value optional="true">CANDLELIGHT 1509 <notes> 1510 Optimized for dim settings where the main light source 1511 is a flame. 1512 </notes> 1513 </value> 1514 <value optional="true">BARCODE 1515 <notes> 1516 Optimized for accurately capturing a photo of barcode 1517 for use by camera applications that wish to read the 1518 barcode value. 1519 </notes> 1520 </value> 1521 <value optional="true">HIGH_SPEED_VIDEO 1522 <notes> 1523 Optimized for high speed video recording (frame rate >=60fps) use case. 1524 1525 The supported high speed video sizes and fps ranges are specified in 1526 android.control.availableHighSpeedVideoConfigurations. To get desired 1527 output frame rates, the application is only allowed to select video size 1528 and fps range combinations listed in this static metadata. The fps range 1529 can be control via android.control.aeTargetFpsRange. 1530 1531 In this mode, the camera device will override aeMode, awbMode, and afMode to 1532 ON, ON, and CONTINUOUS_VIDEO, respectively. All post-processing block mode 1533 controls will be overridden to be FAST. Therefore, no manual control of capture 1534 and post-processing parameters is possible. All other controls operate the 1535 same as when android.control.mode == AUTO. This means that all other 1536 android.control.* fields continue to work, such as 1537 1538 * android.control.aeTargetFpsRange 1539 * android.control.aeExposureCompensation 1540 * android.control.aeLock 1541 * android.control.awbLock 1542 * android.control.effectMode 1543 * android.control.aeRegions 1544 * android.control.afRegions 1545 * android.control.awbRegions 1546 * android.control.afTrigger 1547 * android.control.aePrecaptureTrigger 1548 1549 Outside of android.control.*, the following controls will work: 1550 1551 * android.flash.mode (automatic flash for still capture will not work since aeMode is ON) 1552 * android.lens.opticalStabilizationMode (if it is supported) 1553 * android.scaler.cropRegion 1554 * android.statistics.faceDetectMode 1555 1556 For high speed recording use case, the actual maximum supported frame rate may 1557 be lower than what camera can output, depending on the destination Surfaces for 1558 the image data. For example, if the destination surface is from video encoder, 1559 the application need check if the video encoder is capable of supporting the 1560 high frame rate for a given video size, or it will end up with lower recording 1561 frame rate. If the destination surface is from preview window, the preview frame 1562 rate will be bounded by the screen refresh rate. 1563 1564 The camera device will only support up to 2 output high speed streams 1565 (processed non-stalling format defined in android.request.maxNumOutputStreams) 1566 in this mode. This control will be effective only if all of below conditions are true: 1567 1568 * The application created no more than maxNumHighSpeedStreams processed non-stalling 1569 format output streams, where maxNumHighSpeedStreams is calculated as 1570 min(2, android.request.maxNumOutputStreams[Processed (but not-stalling)]). 1571 * The stream sizes are selected from the sizes reported by 1572 android.control.availableHighSpeedVideoConfigurations. 1573 * No processed non-stalling or raw streams are configured. 1574 1575 When above conditions are NOT satistied, the controls of this mode and 1576 android.control.aeTargetFpsRange will be ignored by the camera device, 1577 the camera device will fall back to android.control.mode `==` AUTO, 1578 and the returned capture result metadata will give the fps range choosen 1579 by the camera device. 1580 1581 Switching into or out of this mode may trigger some camera ISP/sensor 1582 reconfigurations, which may introduce extra latency. It is recommended that 1583 the application avoids unnecessary scene mode switch as much as possible. 1584 </notes> 1585 </value> 1586 <value optional="true">HDR 1587 <notes> 1588 Turn on a device-specific high dynamic range (HDR) mode. 1589 1590 In this scene mode, the camera device captures images 1591 that keep a larger range of scene illumination levels 1592 visible in the final image. For example, when taking a 1593 picture of a object in front of a bright window, both 1594 the object and the scene through the window may be 1595 visible when using HDR mode, while in normal AUTO mode, 1596 one or the other may be poorly exposed. As a tradeoff, 1597 HDR mode generally takes much longer to capture a single 1598 image, has no user control, and may have other artifacts 1599 depending on the HDR method used. 1600 1601 Therefore, HDR captures operate at a much slower rate 1602 than regular captures. 1603 1604 In this mode, on LIMITED or FULL devices, when a request 1605 is made with a android.control.captureIntent of 1606 STILL_CAPTURE, the camera device will capture an image 1607 using a high dynamic range capture technique. On LEGACY 1608 devices, captures that target a JPEG-format output will 1609 be captured with HDR, and the capture intent is not 1610 relevant. 1611 1612 The HDR capture may involve the device capturing a burst 1613 of images internally and combining them into one, or it 1614 may involve the device using specialized high dynamic 1615 range capture hardware. In all cases, a single image is 1616 produced in response to a capture request submitted 1617 while in HDR mode. 1618 1619 Since substantial post-processing is generally needed to 1620 produce an HDR image, only YUV and JPEG outputs are 1621 supported for LIMITED/FULL device HDR captures, and only 1622 JPEG outputs are supported for LEGACY HDR 1623 captures. Using a RAW output for HDR capture is not 1624 supported. 1625 </notes> 1626 </value> 1627 </enum> 1628 <description> 1629 Control for which scene mode is currently active. 1630 </description> 1631 <range>android.control.availableSceneModes</range> 1632 <details> 1633 Scene modes are custom camera modes optimized for a certain set of conditions and 1634 capture settings. 1635 1636 This is the mode that that is active when 1637 `android.control.mode == USE_SCENE_MODE`. Aside from FACE_PRIORITY, 1638 these modes will disable android.control.aeMode, 1639 android.control.awbMode, and android.control.afMode while in use. 1640 1641 The interpretation and implementation of these scene modes is left 1642 to the implementor of the camera device. Their behavior will not be 1643 consistent across all devices, and any given device may only implement 1644 a subset of these modes. 1645 </details> 1646 <hal_details> 1647 HAL implementations that include scene modes are expected to provide 1648 the per-scene settings to use for android.control.aeMode, 1649 android.control.awbMode, and android.control.afMode in 1650 android.control.sceneModeOverrides. 1651 1652 For HIGH_SPEED_VIDEO mode, if it is included in android.control.availableSceneModes, 1653 the HAL must list supported video size and fps range in 1654 android.control.availableHighSpeedVideoConfigurations. For a given size, e.g. 1655 1280x720, if the HAL has two different sensor configurations for normal streaming 1656 mode and high speed streaming, when this scene mode is set/reset in a sequence of capture 1657 requests, the HAL may have to switch between different sensor modes. 1658 </hal_details> 1659 <tag id="BC" /> 1660 </entry> 1661 <entry name="videoStabilizationMode" type="byte" visibility="public" 1662 enum="true" hwlevel="legacy"> 1663 <enum> 1664 <value>OFF 1665 <notes> 1666 Video stabilization is disabled. 1667 </notes></value> 1668 <value>ON 1669 <notes> 1670 Video stabilization is enabled. 1671 </notes></value> 1672 </enum> 1673 <description>Whether video stabilization is 1674 active.</description> 1675 <details> 1676 Video stabilization automatically translates and scales images from 1677 the camera in order to stabilize motion between consecutive frames. 1678 1679 If enabled, video stabilization can modify the 1680 android.scaler.cropRegion to keep the video stream stabilized. 1681 1682 Switching between different video stabilization modes may take several 1683 frames to initialize, the camera device will report the current mode 1684 in capture result metadata. For example, When "ON" mode is requested, 1685 the video stabilization modes in the first several capture results may 1686 still be "OFF", and it will become "ON" when the initialization is 1687 done. 1688 1689 If a camera device supports both this mode and OIS 1690 (android.lens.opticalStabilizationMode), turning both modes on may 1691 produce undesirable interaction, so it is recommended not to enable 1692 both at the same time. 1693 </details> 1694 <tag id="BC" /> 1695 </entry> 1696 </controls> 1697 <static> 1698 <entry name="aeAvailableAntibandingModes" type="byte" visibility="public" 1699 type_notes="list of enums" container="array" typedef="enumList" 1700 hwlevel="legacy"> 1701 <array> 1702 <size>n</size> 1703 </array> 1704 <description> 1705 List of auto-exposure antibanding modes for android.control.aeAntibandingMode that are 1706 supported by this camera device. 1707 </description> 1708 <range>Any value listed in android.control.aeAntibandingMode</range> 1709 <details> 1710 Not all of the auto-exposure anti-banding modes may be 1711 supported by a given camera device. This field lists the 1712 valid anti-banding modes that the application may request 1713 for this camera device with the 1714 android.control.aeAntibandingMode control. 1715 </details> 1716 <tag id="BC" /> 1717 </entry> 1718 <entry name="aeAvailableModes" type="byte" visibility="public" 1719 type_notes="list of enums" container="array" typedef="enumList" 1720 hwlevel="legacy"> 1721 <array> 1722 <size>n</size> 1723 </array> 1724 <description> 1725 List of auto-exposure modes for android.control.aeMode that are supported by this camera 1726 device. 1727 </description> 1728 <range>Any value listed in android.control.aeMode</range> 1729 <details> 1730 Not all the auto-exposure modes may be supported by a 1731 given camera device, especially if no flash unit is 1732 available. This entry lists the valid modes for 1733 android.control.aeMode for this camera device. 1734 1735 All camera devices support ON, and all camera devices with flash 1736 units support ON_AUTO_FLASH and ON_ALWAYS_FLASH. 1737 1738 FULL mode camera devices always support OFF mode, 1739 which enables application control of camera exposure time, 1740 sensitivity, and frame duration. 1741 1742 LEGACY mode camera devices never support OFF mode. 1743 LIMITED mode devices support OFF if they support the MANUAL_SENSOR 1744 capability. 1745 </details> 1746 <tag id="BC" /> 1747 </entry> 1748 <entry name="aeAvailableTargetFpsRanges" type="int32" visibility="public" 1749 type_notes="list of pairs of frame rates" 1750 container="array" typedef="rangeInt" 1751 hwlevel="legacy"> 1752 <array> 1753 <size>2</size> 1754 <size>n</size> 1755 </array> 1756 <description>List of frame rate ranges for android.control.aeTargetFpsRange supported by 1757 this camera device.</description> 1758 <units>Frames per second (FPS)</units> 1759 <details> 1760 For devices at the LIMITED level or above, this list will include at least (30, 30) for 1761 constant-framerate recording. 1762 </details> 1763 <tag id="BC" /> 1764 </entry> 1765 <entry name="aeCompensationRange" type="int32" visibility="public" 1766 container="array" typedef="rangeInt" 1767 hwlevel="legacy"> 1768 <array> 1769 <size>2</size> 1770 </array> 1771 <description>Maximum and minimum exposure compensation values for 1772 android.control.aeExposureCompensation, in counts of android.control.aeCompensationStep, 1773 that are supported by this camera device.</description> 1774 <range> 1775 Range [0,0] indicates that exposure compensation is not supported. 1776 1777 For LIMITED and FULL devices, range must follow below requirements if exposure 1778 compensation is supported (`range != [0, 0]`): 1779 1780 `Min.exposure compensation * android.control.aeCompensationStep <= -2 EV` 1781 1782 `Max.exposure compensation * android.control.aeCompensationStep >= 2 EV` 1783 1784 LEGACY devices may support a smaller range than this. 1785 </range> 1786 <tag id="BC" /> 1787 </entry> 1788 <entry name="aeCompensationStep" type="rational" visibility="public" 1789 hwlevel="legacy"> 1790 <description>Smallest step by which the exposure compensation 1791 can be changed.</description> 1792 <units>Exposure Value (EV)</units> 1793 <details> 1794 This is the unit for android.control.aeExposureCompensation. For example, if this key has 1795 a value of `1/2`, then a setting of `-2` for android.control.aeExposureCompensation means 1796 that the target EV offset for the auto-exposure routine is -1 EV. 1797 1798 One unit of EV compensation changes the brightness of the captured image by a factor 1799 of two. +1 EV doubles the image brightness, while -1 EV halves the image brightness. 1800 </details> 1801 <hal_details> 1802 This must be less than or equal to 1/2. 1803 </hal_details> 1804 <tag id="BC" /> 1805 </entry> 1806 <entry name="afAvailableModes" type="byte" visibility="public" 1807 type_notes="List of enums" container="array" typedef="enumList" 1808 hwlevel="legacy"> 1809 <array> 1810 <size>n</size> 1811 </array> 1812 <description> 1813 List of auto-focus (AF) modes for android.control.afMode that are 1814 supported by this camera device. 1815 </description> 1816 <range>Any value listed in android.control.afMode</range> 1817 <details> 1818 Not all the auto-focus modes may be supported by a 1819 given camera device. This entry lists the valid modes for 1820 android.control.afMode for this camera device. 1821 1822 All LIMITED and FULL mode camera devices will support OFF mode, and all 1823 camera devices with adjustable focuser units 1824 (`android.lens.info.minimumFocusDistance > 0`) will support AUTO mode. 1825 1826 LEGACY devices will support OFF mode only if they support 1827 focusing to infinity (by also setting android.lens.focusDistance to 1828 `0.0f`). 1829 </details> 1830 <tag id="BC" /> 1831 </entry> 1832 <entry name="availableEffects" type="byte" visibility="public" 1833 type_notes="List of enums (android.control.effectMode)." container="array" 1834 typedef="enumList" hwlevel="legacy"> 1835 <array> 1836 <size>n</size> 1837 </array> 1838 <description> 1839 List of color effects for android.control.effectMode that are supported by this camera 1840 device. 1841 </description> 1842 <range>Any value listed in android.control.effectMode</range> 1843 <details> 1844 This list contains the color effect modes that can be applied to 1845 images produced by the camera device. 1846 Implementations are not expected to be consistent across all devices. 1847 If no color effect modes are available for a device, this will only list 1848 OFF. 1849 1850 A color effect will only be applied if 1851 android.control.mode != OFF. OFF is always included in this list. 1852 1853 This control has no effect on the operation of other control routines such 1854 as auto-exposure, white balance, or focus. 1855 </details> 1856 <tag id="BC" /> 1857 </entry> 1858 <entry name="availableSceneModes" type="byte" visibility="public" 1859 type_notes="List of enums (android.control.sceneMode)." 1860 container="array" typedef="enumList" hwlevel="legacy"> 1861 <array> 1862 <size>n</size> 1863 </array> 1864 <description> 1865 List of scene modes for android.control.sceneMode that are supported by this camera 1866 device. 1867 </description> 1868 <range>Any value listed in android.control.sceneMode</range> 1869 <details> 1870 This list contains scene modes that can be set for the camera device. 1871 Only scene modes that have been fully implemented for the 1872 camera device may be included here. Implementations are not expected 1873 to be consistent across all devices. 1874 1875 If no scene modes are supported by the camera device, this 1876 will be set to DISABLED. Otherwise DISABLED will not be listed. 1877 1878 FACE_PRIORITY is always listed if face detection is 1879 supported (i.e.`android.statistics.info.maxFaceCount > 1880 0`). 1881 </details> 1882 <tag id="BC" /> 1883 </entry> 1884 <entry name="availableVideoStabilizationModes" type="byte" 1885 visibility="public" type_notes="List of enums." container="array" 1886 typedef="enumList" hwlevel="legacy"> 1887 <array> 1888 <size>n</size> 1889 </array> 1890 <description> 1891 List of video stabilization modes for android.control.videoStabilizationMode 1892 that are supported by this camera device. 1893 </description> 1894 <range>Any value listed in android.control.videoStabilizationMode</range> 1895 <details> 1896 OFF will always be listed. 1897 </details> 1898 <tag id="BC" /> 1899 </entry> 1900 <entry name="awbAvailableModes" type="byte" visibility="public" 1901 type_notes="List of enums" 1902 container="array" typedef="enumList" hwlevel="legacy"> 1903 <array> 1904 <size>n</size> 1905 </array> 1906 <description> 1907 List of auto-white-balance modes for android.control.awbMode that are supported by this 1908 camera device. 1909 </description> 1910 <range>Any value listed in android.control.awbMode</range> 1911 <details> 1912 Not all the auto-white-balance modes may be supported by a 1913 given camera device. This entry lists the valid modes for 1914 android.control.awbMode for this camera device. 1915 1916 All camera devices will support ON mode. 1917 1918 Camera devices that support the MANUAL_POST_PROCESSING capability will always support OFF 1919 mode, which enables application control of white balance, by using 1920 android.colorCorrection.transform and android.colorCorrection.gains 1921 (android.colorCorrection.mode must be set to TRANSFORM_MATRIX). This includes all FULL 1922 mode camera devices. 1923 </details> 1924 <tag id="BC" /> 1925 </entry> 1926 <entry name="maxRegions" type="int32" visibility="hidden" 1927 container="array" hwlevel="legacy"> 1928 <array> 1929 <size>3</size> 1930 </array> 1931 <description> 1932 List of the maximum number of regions that can be used for metering in 1933 auto-exposure (AE), auto-white balance (AWB), and auto-focus (AF); 1934 this corresponds to the the maximum number of elements in 1935 android.control.aeRegions, android.control.awbRegions, 1936 and android.control.afRegions. 1937 </description> 1938 <range> 1939 Value must be &gt;= 0 for each element. For full-capability devices 1940 this value must be &gt;= 1 for AE and AF. The order of the elements is: 1941 `(AE, AWB, AF)`.</range> 1942 <tag id="BC" /> 1943 </entry> 1944 <entry name="maxRegionsAe" type="int32" visibility="public" 1945 synthetic="true" hwlevel="legacy"> 1946 <description> 1947 The maximum number of metering regions that can be used by the auto-exposure (AE) 1948 routine. 1949 </description> 1950 <range>Value will be &gt;= 0. For FULL-capability devices, this 1951 value will be &gt;= 1. 1952 </range> 1953 <details> 1954 This corresponds to the the maximum allowed number of elements in 1955 android.control.aeRegions. 1956 </details> 1957 <hal_details>This entry is private to the framework. Fill in 1958 maxRegions to have this entry be automatically populated. 1959 </hal_details> 1960 </entry> 1961 <entry name="maxRegionsAwb" type="int32" visibility="public" 1962 synthetic="true" hwlevel="legacy"> 1963 <description> 1964 The maximum number of metering regions that can be used by the auto-white balance (AWB) 1965 routine. 1966 </description> 1967 <range>Value will be &gt;= 0. 1968 </range> 1969 <details> 1970 This corresponds to the the maximum allowed number of elements in 1971 android.control.awbRegions. 1972 </details> 1973 <hal_details>This entry is private to the framework. Fill in 1974 maxRegions to have this entry be automatically populated. 1975 </hal_details> 1976 </entry> 1977 <entry name="maxRegionsAf" type="int32" visibility="public" 1978 synthetic="true" hwlevel="legacy"> 1979 <description> 1980 The maximum number of metering regions that can be used by the auto-focus (AF) routine. 1981 </description> 1982 <range>Value will be &gt;= 0. For FULL-capability devices, this 1983 value will be &gt;= 1. 1984 </range> 1985 <details> 1986 This corresponds to the the maximum allowed number of elements in 1987 android.control.afRegions. 1988 </details> 1989 <hal_details>This entry is private to the framework. Fill in 1990 maxRegions to have this entry be automatically populated. 1991 </hal_details> 1992 </entry> 1993 <entry name="sceneModeOverrides" type="byte" visibility="system" 1994 container="array" hwlevel="limited"> 1995 <array> 1996 <size>3</size> 1997 <size>length(availableSceneModes)</size> 1998 </array> 1999 <description> 2000 Ordered list of auto-exposure, auto-white balance, and auto-focus 2001 settings to use with each available scene mode. 2002 </description> 2003 <range> 2004 For each available scene mode, the list must contain three 2005 entries containing the android.control.aeMode, 2006 android.control.awbMode, and android.control.afMode values used 2007 by the camera device. The entry order is `(aeMode, awbMode, afMode)` 2008 where aeMode has the lowest index position. 2009 </range> 2010 <details> 2011 When a scene mode is enabled, the camera device is expected 2012 to override android.control.aeMode, android.control.awbMode, 2013 and android.control.afMode with its preferred settings for 2014 that scene mode. 2015 2016 The order of this list matches that of availableSceneModes, 2017 with 3 entries for each mode. The overrides listed 2018 for FACE_PRIORITY are ignored, since for that 2019 mode the application-set android.control.aeMode, 2020 android.control.awbMode, and android.control.afMode values are 2021 used instead, matching the behavior when android.control.mode 2022 is set to AUTO. It is recommended that the FACE_PRIORITY 2023 overrides should be set to 0. 2024 2025 For example, if availableSceneModes contains 2026 `(FACE_PRIORITY, ACTION, NIGHT)`, then the camera framework 2027 expects sceneModeOverrides to have 9 entries formatted like: 2028 `(0, 0, 0, ON_AUTO_FLASH, AUTO, CONTINUOUS_PICTURE, 2029 ON_AUTO_FLASH, INCANDESCENT, AUTO)`. 2030 </details> 2031 <hal_details> 2032 To maintain backward compatibility, this list will be made available 2033 in the static metadata of the camera service. The camera service will 2034 use these values to set android.control.aeMode, 2035 android.control.awbMode, and android.control.afMode when using a scene 2036 mode other than FACE_PRIORITY. 2037 </hal_details> 2038 <tag id="BC" /> 2039 </entry> 2040 </static> 2041 <dynamic> 2042 <entry name="aePrecaptureId" type="int32" visibility="system" deprecated="true"> 2043 <description>The ID sent with the latest 2044 CAMERA2_TRIGGER_PRECAPTURE_METERING call</description> 2045 <details>Must be 0 if no 2046 CAMERA2_TRIGGER_PRECAPTURE_METERING trigger received yet 2047 by HAL. Always updated even if AE algorithm ignores the 2048 trigger</details> 2049 </entry> 2050 <clone entry="android.control.aeAntibandingMode" kind="controls"> 2051 </clone> 2052 <clone entry="android.control.aeExposureCompensation" kind="controls"> 2053 </clone> 2054 <clone entry="android.control.aeLock" kind="controls"> 2055 </clone> 2056 <clone entry="android.control.aeMode" kind="controls"> 2057 </clone> 2058 <clone entry="android.control.aeRegions" kind="controls"> 2059 </clone> 2060 <clone entry="android.control.aeTargetFpsRange" kind="controls"> 2061 </clone> 2062 <clone entry="android.control.aePrecaptureTrigger" kind="controls"> 2063 </clone> 2064 <entry name="aeState" type="byte" visibility="public" enum="true" 2065 hwlevel="limited"> 2066 <enum> 2067 <value>INACTIVE 2068 <notes>AE is off or recently reset. 2069 2070 When a camera device is opened, it starts in 2071 this state. This is a transient state, the camera device may skip reporting 2072 this state in capture result.</notes></value> 2073 <value>SEARCHING 2074 <notes>AE doesn't yet have a good set of control values 2075 for the current scene. 2076 2077 This is a transient state, the camera device may skip 2078 reporting this state in capture result.</notes></value> 2079 <value>CONVERGED 2080 <notes>AE has a good set of control values for the 2081 current scene.</notes></value> 2082 <value>LOCKED 2083 <notes>AE has been locked.</notes></value> 2084 <value>FLASH_REQUIRED 2085 <notes>AE has a good set of control values, but flash 2086 needs to be fired for good quality still 2087 capture.</notes></value> 2088 <value>PRECAPTURE 2089 <notes>AE has been asked to do a precapture sequence 2090 and is currently executing it. 2091 2092 Precapture can be triggered through setting 2093 android.control.aePrecaptureTrigger to START. 2094 2095 Once PRECAPTURE completes, AE will transition to CONVERGED 2096 or FLASH_REQUIRED as appropriate. This is a transient 2097 state, the camera device may skip reporting this state in 2098 capture result.</notes></value> 2099 </enum> 2100 <description>Current state of the auto-exposure (AE) algorithm.</description> 2101 <details>Switching between or enabling AE modes (android.control.aeMode) always 2102 resets the AE state to INACTIVE. Similarly, switching between android.control.mode, 2103 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2104 the algorithm states to INACTIVE. 2105 2106 The camera device can do several state transitions between two results, if it is 2107 allowed by the state transition table. For example: INACTIVE may never actually be 2108 seen in a result. 2109 2110 The state in the result is the state for this image (in sync with this image): if 2111 AE state becomes CONVERGED, then the image data associated with this result should 2112 be good to use. 2113 2114 Below are state transition tables for different AE modes. 2115 2116 State | Transition Cause | New State | Notes 2117 :------------:|:----------------:|:---------:|:-----------------------: 2118 INACTIVE | | INACTIVE | Camera device auto exposure algorithm is disabled 2119 2120 When android.control.aeMode is AE_MODE_ON_*: 2121 2122 State | Transition Cause | New State | Notes 2123 :-------------:|:--------------------------------------------:|:--------------:|:-----------------: 2124 INACTIVE | Camera device initiates AE scan | SEARCHING | Values changing 2125 INACTIVE | android.control.aeLock is ON | LOCKED | Values locked 2126 SEARCHING | Camera device finishes AE scan | CONVERGED | Good values, not changing 2127 SEARCHING | Camera device finishes AE scan | FLASH_REQUIRED | Converged but too dark w/o flash 2128 SEARCHING | android.control.aeLock is ON | LOCKED | Values locked 2129 CONVERGED | Camera device initiates AE scan | SEARCHING | Values changing 2130 CONVERGED | android.control.aeLock is ON | LOCKED | Values locked 2131 FLASH_REQUIRED | Camera device initiates AE scan | SEARCHING | Values changing 2132 FLASH_REQUIRED | android.control.aeLock is ON | LOCKED | Values locked 2133 LOCKED | android.control.aeLock is OFF | SEARCHING | Values not good after unlock 2134 LOCKED | android.control.aeLock is OFF | CONVERGED | Values good after unlock 2135 LOCKED | android.control.aeLock is OFF | FLASH_REQUIRED | Exposure good, but too dark 2136 PRECAPTURE | Sequence done. android.control.aeLock is OFF | CONVERGED | Ready for high-quality capture 2137 PRECAPTURE | Sequence done. android.control.aeLock is ON | LOCKED | Ready for high-quality capture 2138 Any state | android.control.aePrecaptureTrigger is START | PRECAPTURE | Start AE precapture metering sequence 2139 2140 For the above table, the camera device may skip reporting any state changes that happen 2141 without application intervention (i.e. mode switch, trigger, locking). Any state that 2142 can be skipped in that manner is called a transient state. 2143 2144 For example, for above AE modes (AE_MODE_ON_*), in addition to the state transitions 2145 listed in above table, it is also legal for the camera device to skip one or more 2146 transient states between two results. See below table for examples: 2147 2148 State | Transition Cause | New State | Notes 2149 :-------------:|:-----------------------------------------------------------:|:--------------:|:-----------------: 2150 INACTIVE | Camera device finished AE scan | CONVERGED | Values are already good, transient states are skipped by camera device. 2151 Any state | 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. 2152 Any state | android.control.aePrecaptureTrigger is START, sequence done | CONVERGED | Converged after a precapture sequence, transient states are skipped by camera device. 2153 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. 2154 FLASH_REQUIRED | Camera device finished AE scan | CONVERGED | Converged after a new scan, transient states are skipped by camera device. 2155 </details> 2156 </entry> 2157 <clone entry="android.control.afMode" kind="controls"> 2158 </clone> 2159 <clone entry="android.control.afRegions" kind="controls"> 2160 </clone> 2161 <clone entry="android.control.afTrigger" kind="controls"> 2162 </clone> 2163 <entry name="afState" type="byte" visibility="public" enum="true" 2164 hwlevel="legacy"> 2165 <enum> 2166 <value>INACTIVE 2167 <notes>AF is off or has not yet tried to scan/been asked 2168 to scan. 2169 2170 When a camera device is opened, it starts in this 2171 state. This is a transient state, the camera device may 2172 skip reporting this state in capture 2173 result.</notes></value> 2174 <value>PASSIVE_SCAN 2175 <notes>AF is currently performing an AF scan initiated the 2176 camera device in a continuous autofocus mode. 2177 2178 Only used by CONTINUOUS_* AF modes. This is a transient 2179 state, the camera device may skip reporting this state in 2180 capture result.</notes></value> 2181 <value>PASSIVE_FOCUSED 2182 <notes>AF currently believes it is in focus, but may 2183 restart scanning at any time. 2184 2185 Only used by CONTINUOUS_* AF modes. This is a transient 2186 state, the camera device may skip reporting this state in 2187 capture result.</notes></value> 2188 <value>ACTIVE_SCAN 2189 <notes>AF is performing an AF scan because it was 2190 triggered by AF trigger. 2191 2192 Only used by AUTO or MACRO AF modes. This is a transient 2193 state, the camera device may skip reporting this state in 2194 capture result.</notes></value> 2195 <value>FOCUSED_LOCKED 2196 <notes>AF believes it is focused correctly and has locked 2197 focus. 2198 2199 This state is reached only after an explicit START AF trigger has been 2200 sent (android.control.afTrigger), when good focus has been obtained. 2201 2202 The lens will remain stationary until the AF mode (android.control.afMode) is changed or 2203 a new AF trigger is sent to the camera device (android.control.afTrigger). 2204 </notes></value> 2205 <value>NOT_FOCUSED_LOCKED 2206 <notes>AF has failed to focus successfully and has locked 2207 focus. 2208 2209 This state is reached only after an explicit START AF trigger has been 2210 sent (android.control.afTrigger), when good focus cannot be obtained. 2211 2212 The lens will remain stationary until the AF mode (android.control.afMode) is changed or 2213 a new AF trigger is sent to the camera device (android.control.afTrigger). 2214 </notes></value> 2215 <value>PASSIVE_UNFOCUSED 2216 <notes>AF finished a passive scan without finding focus, 2217 and may restart scanning at any time. 2218 2219 Only used by CONTINUOUS_* AF modes. This is a transient state, the camera 2220 device may skip reporting this state in capture result. 2221 2222 LEGACY camera devices do not support this state. When a passive 2223 scan has finished, it will always go to PASSIVE_FOCUSED. 2224 </notes></value> 2225 </enum> 2226 <description>Current state of auto-focus (AF) algorithm.</description> 2227 <details> 2228 Switching between or enabling AF modes (android.control.afMode) always 2229 resets the AF state to INACTIVE. Similarly, switching between android.control.mode, 2230 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2231 the algorithm states to INACTIVE. 2232 2233 The camera device can do several state transitions between two results, if it is 2234 allowed by the state transition table. For example: INACTIVE may never actually be 2235 seen in a result. 2236 2237 The state in the result is the state for this image (in sync with this image): if 2238 AF state becomes FOCUSED, then the image data associated with this result should 2239 be sharp. 2240 2241 Below are state transition tables for different AF modes. 2242 2243 When android.control.afMode is AF_MODE_OFF or AF_MODE_EDOF: 2244 2245 State | Transition Cause | New State | Notes 2246 :------------:|:----------------:|:---------:|:-----------: 2247 INACTIVE | | INACTIVE | Never changes 2248 2249 When android.control.afMode is AF_MODE_AUTO or AF_MODE_MACRO: 2250 2251 State | Transition Cause | New State | Notes 2252 :-----------------:|:----------------:|:------------------:|:--------------: 2253 INACTIVE | AF_TRIGGER | ACTIVE_SCAN | Start AF sweep, Lens now moving 2254 ACTIVE_SCAN | AF sweep done | FOCUSED_LOCKED | Focused, Lens now locked 2255 ACTIVE_SCAN | AF sweep done | NOT_FOCUSED_LOCKED | Not focused, Lens now locked 2256 ACTIVE_SCAN | AF_CANCEL | INACTIVE | Cancel/reset AF, Lens now locked 2257 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF 2258 FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving 2259 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF 2260 NOT_FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving 2261 Any state | Mode change | INACTIVE | 2262 2263 For the above table, the camera device may skip reporting any state changes that happen 2264 without application intervention (i.e. mode switch, trigger, locking). Any state that 2265 can be skipped in that manner is called a transient state. 2266 2267 For example, for these AF modes (AF_MODE_AUTO and AF_MODE_MACRO), in addition to the 2268 state transitions listed in above table, it is also legal for the camera device to skip 2269 one or more transient states between two results. See below table for examples: 2270 2271 State | Transition Cause | New State | Notes 2272 :-----------------:|:----------------:|:------------------:|:--------------: 2273 INACTIVE | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. 2274 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | Focus failed after a scan, lens is now locked. 2275 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. 2276 NOT_FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is good after a scan, lens is not locked. 2277 2278 2279 When android.control.afMode is AF_MODE_CONTINUOUS_VIDEO: 2280 2281 State | Transition Cause | New State | Notes 2282 :-----------------:|:-----------------------------------:|:------------------:|:--------------: 2283 INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2284 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked 2285 PASSIVE_SCAN | Camera device completes current scan| PASSIVE_FOCUSED | End AF scan, Lens now locked 2286 PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, Lens now locked 2287 PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Immediate transition, if focus is good. Lens now locked 2288 PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate transition, if focus is bad. Lens now locked 2289 PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens position, Lens now locked 2290 PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2291 PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2292 PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate transition, lens now locked 2293 PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate transition, lens now locked 2294 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect 2295 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2296 NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect 2297 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2298 2299 When android.control.afMode is AF_MODE_CONTINUOUS_PICTURE: 2300 2301 State | Transition Cause | New State | Notes 2302 :-----------------:|:------------------------------------:|:------------------:|:--------------: 2303 INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2304 INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked 2305 PASSIVE_SCAN | Camera device completes current scan | PASSIVE_FOCUSED | End AF scan, Lens now locked 2306 PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, Lens now locked 2307 PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Eventual transition once the focus is good. Lens now locked 2308 PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Eventual transition if cannot find focus. Lens now locked 2309 PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens position, Lens now locked 2310 PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2311 PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving 2312 PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. Lens now locked 2313 PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. Lens now locked 2314 FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | No effect 2315 FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2316 NOT_FOCUSED_LOCKED | AF_TRIGGER | NOT_FOCUSED_LOCKED | No effect 2317 NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Restart AF scan 2318 2319 When switch between AF_MODE_CONTINUOUS_* (CAF modes) and AF_MODE_AUTO/AF_MODE_MACRO 2320 (AUTO modes), the initial INACTIVE or PASSIVE_SCAN states may be skipped by the 2321 camera device. When a trigger is included in a mode switch request, the trigger 2322 will be evaluated in the context of the new mode in the request. 2323 See below table for examples: 2324 2325 State | Transition Cause | New State | Notes 2326 :-----------:|:--------------------------------------:|:----------------------------------------:|:--------------: 2327 any state | CAF-->AUTO mode switch | INACTIVE | Mode switch without trigger, initial state must be INACTIVE 2328 any state | CAF-->AUTO mode switch with AF_TRIGGER | trigger-reachable states from INACTIVE | Mode switch with trigger, INACTIVE is skipped 2329 any state | AUTO-->CAF mode switch | passively reachable states from INACTIVE | Mode switch without trigger, passive transient state is skipped 2330 </details> 2331 </entry> 2332 <entry name="afTriggerId" type="int32" visibility="system" deprecated="true"> 2333 <description>The ID sent with the latest 2334 CAMERA2_TRIGGER_AUTOFOCUS call</description> 2335 <details>Must be 0 if no CAMERA2_TRIGGER_AUTOFOCUS trigger 2336 received yet by HAL. Always updated even if AF algorithm 2337 ignores the trigger</details> 2338 </entry> 2339 <clone entry="android.control.awbLock" kind="controls"> 2340 </clone> 2341 <clone entry="android.control.awbMode" kind="controls"> 2342 </clone> 2343 <clone entry="android.control.awbRegions" kind="controls"> 2344 </clone> 2345 <clone entry="android.control.captureIntent" kind="controls"> 2346 </clone> 2347 <entry name="awbState" type="byte" visibility="public" enum="true" 2348 hwlevel="limited"> 2349 <enum> 2350 <value>INACTIVE 2351 <notes>AWB is not in auto mode, or has not yet started metering. 2352 2353 When a camera device is opened, it starts in this 2354 state. This is a transient state, the camera device may 2355 skip reporting this state in capture 2356 result.</notes></value> 2357 <value>SEARCHING 2358 <notes>AWB doesn't yet have a good set of control 2359 values for the current scene. 2360 2361 This is a transient state, the camera device 2362 may skip reporting this state in capture result.</notes></value> 2363 <value>CONVERGED 2364 <notes>AWB has a good set of control values for the 2365 current scene.</notes></value> 2366 <value>LOCKED 2367 <notes>AWB has been locked. 2368 </notes></value> 2369 </enum> 2370 <description>Current state of auto-white balance (AWB) algorithm.</description> 2371 <details>Switching between or enabling AWB modes (android.control.awbMode) always 2372 resets the AWB state to INACTIVE. Similarly, switching between android.control.mode, 2373 or android.control.sceneMode if `android.control.mode == USE_SCENE_MODE` resets all 2374 the algorithm states to INACTIVE. 2375 2376 The camera device can do several state transitions between two results, if it is 2377 allowed by the state transition table. So INACTIVE may never actually be seen in 2378 a result. 2379 2380 The state in the result is the state for this image (in sync with this image): if 2381 AWB state becomes CONVERGED, then the image data associated with this result should 2382 be good to use. 2383 2384 Below are state transition tables for different AWB modes. 2385 2386 When `android.control.awbMode != AWB_MODE_AUTO`: 2387 2388 State | Transition Cause | New State | Notes 2389 :------------:|:----------------:|:---------:|:-----------------------: 2390 INACTIVE | |INACTIVE |Camera device auto white balance algorithm is disabled 2391 2392 When android.control.awbMode is AWB_MODE_AUTO: 2393 2394 State | Transition Cause | New State | Notes 2395 :-------------:|:--------------------------------:|:-------------:|:-----------------: 2396 INACTIVE | Camera device initiates AWB scan | SEARCHING | Values changing 2397 INACTIVE | android.control.awbLock is ON | LOCKED | Values locked 2398 SEARCHING | Camera device finishes AWB scan | CONVERGED | Good values, not changing 2399 SEARCHING | android.control.awbLock is ON | LOCKED | Values locked 2400 CONVERGED | Camera device initiates AWB scan | SEARCHING | Values changing 2401 CONVERGED | android.control.awbLock is ON | LOCKED | Values locked 2402 LOCKED | android.control.awbLock is OFF | SEARCHING | Values not good after unlock 2403 2404 For the above table, the camera device may skip reporting any state changes that happen 2405 without application intervention (i.e. mode switch, trigger, locking). Any state that 2406 can be skipped in that manner is called a transient state. 2407 2408 For example, for this AWB mode (AWB_MODE_AUTO), in addition to the state transitions 2409 listed in above table, it is also legal for the camera device to skip one or more 2410 transient states between two results. See below table for examples: 2411 2412 State | Transition Cause | New State | Notes 2413 :-------------:|:--------------------------------:|:-------------:|:-----------------: 2414 INACTIVE | Camera device finished AWB scan | CONVERGED | Values are already good, transient states are skipped by camera device. 2415 LOCKED | android.control.awbLock is OFF | CONVERGED | Values good after unlock, transient states are skipped by camera device. 2416 </details> 2417 </entry> 2418 <clone entry="android.control.effectMode" kind="controls"> 2419 </clone> 2420 <clone entry="android.control.mode" kind="controls"> 2421 </clone> 2422 <clone entry="android.control.sceneMode" kind="controls"> 2423 </clone> 2424 <clone entry="android.control.videoStabilizationMode" kind="controls"> 2425 </clone> 2426 </dynamic> 2427 <static> 2428 <entry name="availableHighSpeedVideoConfigurations" type="int32" visibility="hidden" 2429 container="array" typedef="highSpeedVideoConfiguration" hwlevel="limited"> 2430 <array> 2431 <size>4</size> 2432 <size>n</size> 2433 </array> 2434 <description> 2435 List of available high speed video size and fps range configurations 2436 supported by the camera device, in the format of (width, height, fps_min, fps_max). 2437 </description> 2438 <range> 2439 For each configuration, the fps_max &gt;= 60fps. 2440 </range> 2441 <details> 2442 When HIGH_SPEED_VIDEO is supported in android.control.availableSceneModes, 2443 this metadata will list the supported high speed video size and fps range 2444 configurations. All the sizes listed in this configuration will be a subset 2445 of the sizes reported by StreamConfigurationMap#getOutputSizes for processed 2446 non-stalling formats. 2447 2448 For the high speed video use case, where the application will set 2449 android.control.sceneMode to HIGH_SPEED_VIDEO in capture requests, the application must 2450 select the video size and fps range from this metadata to configure the recording and 2451 preview streams and setup the recording requests. For example, if the application intends 2452 to do high speed recording, it can select the maximum size reported by this metadata to 2453 configure output streams. Once the size is selected, application can filter this metadata 2454 by selected size and get the supported fps ranges, and use these fps ranges to setup the 2455 recording requests. Note that for the use case of multiple output streams, application 2456 must select one unique size from this metadata to use. Otherwise a request error might 2457 occur. 2458 2459 For normal video recording use case, where some application will NOT set 2460 android.control.sceneMode to HIGH_SPEED_VIDEO in capture requests, the fps ranges 2461 reported in this metadata must not be used to setup capture requests, or it will cause 2462 request error. 2463 </details> 2464 <hal_details> 2465 All the sizes listed in this configuration will be a subset of the sizes reported by 2466 android.scaler.availableStreamConfigurations for processed non-stalling output formats. 2467 Note that for all high speed video configurations, HAL must be able to support a minimum 2468 of two streams, though the application might choose to configure just one stream. 2469 2470 Since the HIGH_SPEED_VIDEO mode may be turned on for preview view only case, the preview 2471 fps is bounded by device refresh rate (e.g. 60fps). For a given resolution, it is 2472 recommended that this list includes some fps ranges (e.g. [30, 60]) that is suitable 2473 for preview only streaming case. 2474 </hal_details> 2475 <tag id="V1" /> 2476 </entry> 2477 </static> 2478 </section> 2479 <section name="demosaic"> 2480 <controls> 2481 <entry name="mode" type="byte" enum="true"> 2482 <enum> 2483 <value>FAST 2484 <notes>Minimal or no slowdown of frame rate compared to 2485 Bayer RAW output.</notes></value> 2486 <value>HIGH_QUALITY 2487 <notes>Improved processing quality but the frame rate is slowed down 2488 relative to raw output.</notes></value> 2489 </enum> 2490 <description>Controls the quality of the demosaicing 2491 processing.</description> 2492 <tag id="FUTURE" /> 2493 </entry> 2494 </controls> 2495 </section> 2496 <section name="edge"> 2497 <controls> 2498 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 2499 <enum> 2500 <value>OFF 2501 <notes>No edge enhancement is applied.</notes></value> 2502 <value>FAST 2503 <notes>Apply edge enhancement at a quality level that does not slow down frame rate relative to sensor 2504 output</notes></value> 2505 <value>HIGH_QUALITY 2506 <notes>Apply high-quality edge enhancement, at a cost of reducing output frame rate. 2507 </notes></value> 2508 </enum> 2509 <description>Operation mode for edge 2510 enhancement.</description> 2511 <range>android.edge.availableEdgeModes</range> 2512 <details>Edge enhancement improves sharpness and details in the captured image. OFF means 2513 no enhancement will be applied by the camera device. 2514 2515 FAST/HIGH_QUALITY both mean camera device determined enhancement 2516 will be applied. HIGH_QUALITY mode indicates that the 2517 camera device will use the highest-quality enhancement algorithms, 2518 even if it slows down capture rate. FAST means the camera device will 2519 not slow down capture rate when applying edge enhancement.</details> 2520 <tag id="V1" /> 2521 </entry> 2522 <entry name="strength" type="byte"> 2523 <description>Control the amount of edge enhancement 2524 applied to the images</description> 2525 <units>1-10; 10 is maximum sharpening</units> 2526 <tag id="FUTURE" /> 2527 </entry> 2528 </controls> 2529 <static> 2530 <entry name="availableEdgeModes" type="byte" visibility="public" 2531 type_notes="list of enums" container="array" typedef="enumList" 2532 hwlevel="full"> 2533 <array> 2534 <size>n</size> 2535 </array> 2536 <description> 2537 List of edge enhancement modes for android.edge.mode that are supported by this camera 2538 device. 2539 </description> 2540 <range>Any value listed in android.edge.mode</range> 2541 <details> 2542 Full-capability camera devices must always support OFF; all devices will list FAST. 2543 </details> 2544 <tag id="V1" /> 2545 </entry> 2546 </static> 2547 <dynamic> 2548 <clone entry="android.edge.mode" kind="controls"> 2549 <tag id="V1" /> 2550 </clone> 2551 </dynamic> 2552 </section> 2553 <section name="flash"> 2554 <controls> 2555 <entry name="firingPower" type="byte"> 2556 <description>Power for flash firing/torch</description> 2557 <units>10 is max power; 0 is no flash. Linear</units> 2558 <range>0 - 10</range> 2559 <details>Power for snapshot may use a different scale than 2560 for torch mode. Only one entry for torch mode will be 2561 used</details> 2562 <tag id="FUTURE" /> 2563 </entry> 2564 <entry name="firingTime" type="int64"> 2565 <description>Firing time of flash relative to start of 2566 exposure</description> 2567 <units>nanoseconds</units> 2568 <range>0-(exposure time-flash duration)</range> 2569 <details>Clamped to (0, exposure time - flash 2570 duration).</details> 2571 <tag id="FUTURE" /> 2572 </entry> 2573 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="legacy"> 2574 <enum> 2575 <value>OFF 2576 <notes> 2577 Do not fire the flash for this capture. 2578 </notes> 2579 </value> 2580 <value>SINGLE 2581 <notes> 2582 If the flash is available and charged, fire flash 2583 for this capture. 2584 </notes> 2585 </value> 2586 <value>TORCH 2587 <notes> 2588 Transition flash to continuously on. 2589 </notes> 2590 </value> 2591 </enum> 2592 <description>The desired mode for for the camera device's flash control.</description> 2593 <details> 2594 This control is only effective when flash unit is available 2595 (`android.flash.info.available == true`). 2596 2597 When this control is used, the android.control.aeMode must be set to ON or OFF. 2598 Otherwise, the camera device auto-exposure related flash control (ON_AUTO_FLASH, 2599 ON_ALWAYS_FLASH, or ON_AUTO_FLASH_REDEYE) will override this control. 2600 2601 When set to OFF, the camera device will not fire flash for this capture. 2602 2603 When set to SINGLE, the camera device will fire flash regardless of the camera 2604 device's auto-exposure routine's result. When used in still capture case, this 2605 control should be used along with auto-exposure (AE) precapture metering sequence 2606 (android.control.aePrecaptureTrigger), otherwise, the image may be incorrectly exposed. 2607 2608 When set to TORCH, the flash will be on continuously. This mode can be used 2609 for use cases such as preview, auto-focus assist, still capture, or video recording. 2610 2611 The flash status will be reported by android.flash.state in the capture result metadata. 2612 </details> 2613 <tag id="BC" /> 2614 </entry> 2615 </controls> 2616 <static> 2617 <namespace name="info"> 2618 <entry name="available" type="byte" visibility="public" enum="true" 2619 typedef="boolean" hwlevel="legacy"> 2620 <enum> 2621 <value>FALSE</value> 2622 <value>TRUE</value> 2623 </enum> 2624 <description>Whether this camera device has a 2625 flash unit.</description> 2626 <details> 2627 Will be `false` if no flash is available. 2628 2629 If there is no flash unit, none of the flash controls do 2630 anything.</details> 2631 <tag id="BC" /> 2632 </entry> 2633 <entry name="chargeDuration" type="int64"> 2634 <description>Time taken before flash can fire 2635 again</description> 2636 <units>nanoseconds</units> 2637 <range>0-1e9</range> 2638 <details>1 second too long/too short for recharge? Should 2639 this be power-dependent?</details> 2640 <tag id="FUTURE" /> 2641 </entry> 2642 </namespace> 2643 <entry name="colorTemperature" type="byte"> 2644 <description>The x,y whitepoint of the 2645 flash</description> 2646 <units>pair of floats</units> 2647 <range>0-1 for both</range> 2648 <tag id="FUTURE" /> 2649 </entry> 2650 <entry name="maxEnergy" type="byte"> 2651 <description>Max energy output of the flash for a full 2652 power single flash</description> 2653 <units>lumen-seconds</units> 2654 <range>&gt;= 0</range> 2655 <tag id="FUTURE" /> 2656 </entry> 2657 </static> 2658 <dynamic> 2659 <clone entry="android.flash.firingPower" kind="controls"> 2660 </clone> 2661 <clone entry="android.flash.firingTime" kind="controls"> 2662 </clone> 2663 <clone entry="android.flash.mode" kind="controls"></clone> 2664 <entry name="state" type="byte" visibility="public" enum="true" 2665 hwlevel="limited"> 2666 <enum> 2667 <value>UNAVAILABLE 2668 <notes>No flash on camera.</notes></value> 2669 <value>CHARGING 2670 <notes>Flash is charging and cannot be fired.</notes></value> 2671 <value>READY 2672 <notes>Flash is ready to fire.</notes></value> 2673 <value>FIRED 2674 <notes>Flash fired for this capture.</notes></value> 2675 <value>PARTIAL 2676 <notes>Flash partially illuminated this frame. 2677 2678 This is usually due to the next or previous frame having 2679 the flash fire, and the flash spilling into this capture 2680 due to hardware limitations.</notes></value> 2681 </enum> 2682 <description>Current state of the flash 2683 unit.</description> 2684 <details> 2685 When the camera device doesn't have flash unit 2686 (i.e. `android.flash.info.available == false`), this state will always be UNAVAILABLE. 2687 Other states indicate the current flash status. 2688 2689 In certain conditions, this will be available on LEGACY devices: 2690 2691 * Flash-less cameras always return UNAVAILABLE. 2692 * Using android.control.aeMode `==` ON_ALWAYS_FLASH 2693 will always return FIRED. 2694 * Using android.flash.mode `==` TORCH 2695 will always return FIRED. 2696 2697 In all other conditions the state will not be available on 2698 LEGACY devices (i.e. it will be `null`). 2699 </details> 2700 </entry> 2701 </dynamic> 2702 </section> 2703 <section name="hotPixel"> 2704 <controls> 2705 <entry name="mode" type="byte" visibility="public" enum="true"> 2706 <enum> 2707 <value>OFF 2708 <notes> 2709 No hot pixel correction is applied. 2710 2711 The frame rate must not be reduced relative to sensor raw output 2712 for this option. 2713 2714 The hotpixel map may be returned in android.statistics.hotPixelMap. 2715 </notes> 2716 </value> 2717 <value>FAST 2718 <notes> 2719 Hot pixel correction is applied, without reducing frame 2720 rate relative to sensor raw output. 2721 2722 The hotpixel map may be returned in android.statistics.hotPixelMap. 2723 </notes> 2724 </value> 2725 <value>HIGH_QUALITY 2726 <notes> 2727 High-quality hot pixel correction is applied, at a cost 2728 of reducing frame rate relative to sensor raw output. 2729 2730 The hotpixel map may be returned in android.statistics.hotPixelMap. 2731 </notes> 2732 </value> 2733 </enum> 2734 <description> 2735 Operational mode for hot pixel correction. 2736 </description> 2737 <range>android.hotPixel.availableHotPixelModes</range> 2738 <details> 2739 Hotpixel correction interpolates out, or otherwise removes, pixels 2740 that do not accurately measure the incoming light (i.e. pixels that 2741 are stuck at an arbitrary value or are oversensitive). 2742 </details> 2743 <tag id="V1" /> 2744 <tag id="RAW" /> 2745 </entry> 2746 </controls> 2747 <static> 2748 <entry name="availableHotPixelModes" type="byte" visibility="public" 2749 type_notes="list of enums" container="array" typedef="enumList"> 2750 <array> 2751 <size>n</size> 2752 </array> 2753 <description> 2754 List of hot pixel correction modes for android.hotPixel.mode that are supported by this 2755 camera device. 2756 </description> 2757 <range>Any value listed in android.hotPixel.mode</range> 2758 <details> 2759 FULL mode camera devices will always support FAST. 2760 </details> 2761 <hal_details> 2762 To avoid performance issues, there will be significantly fewer hot 2763 pixels than actual pixels on the camera sensor. 2764 </hal_details> 2765 <tag id="V1" /> 2766 <tag id="RAW" /> 2767 </entry> 2768 </static> 2769 <dynamic> 2770 <clone entry="android.hotPixel.mode" kind="controls"> 2771 <tag id="V1" /> 2772 <tag id="RAW" /> 2773 </clone> 2774 </dynamic> 2775 </section> 2776 <section name="jpeg"> 2777 <controls> 2778 <entry name="gpsLocation" type="byte" visibility="public" synthetic="true" 2779 typedef="location" hwlevel="legacy"> 2780 <description> 2781 A location object to use when generating image GPS metadata. 2782 </description> 2783 <details> 2784 Setting a location object in a request will include the GPS coordinates of the location 2785 into any JPEG images captured based on the request. These coordinates can then be 2786 viewed by anyone who receives the JPEG image. 2787 </details> 2788 </entry> 2789 <entry name="gpsCoordinates" type="double" visibility="hidden" 2790 type_notes="latitude, longitude, altitude. First two in degrees, the third in meters" 2791 container="array" hwlevel="legacy"> 2792 <array> 2793 <size>3</size> 2794 </array> 2795 <description>GPS coordinates to include in output JPEG 2796 EXIF.</description> 2797 <range>(-180 - 180], [-90,90], [-inf, inf]</range> 2798 <tag id="BC" /> 2799 </entry> 2800 <entry name="gpsProcessingMethod" type="byte" visibility="hidden" 2801 typedef="string" hwlevel="legacy"> 2802 <description>32 characters describing GPS algorithm to 2803 include in EXIF.</description> 2804 <units>UTF-8 null-terminated string</units> 2805 <tag id="BC" /> 2806 </entry> 2807 <entry name="gpsTimestamp" type="int64" visibility="hidden" hwlevel="legacy"> 2808 <description>Time GPS fix was made to include in 2809 EXIF.</description> 2810 <units>UTC in seconds since January 1, 1970</units> 2811 <tag id="BC" /> 2812 </entry> 2813 <entry name="orientation" type="int32" visibility="public" hwlevel="legacy"> 2814 <description>The orientation for a JPEG image.</description> 2815 <units>Degrees in multiples of 90</units> 2816 <range>0, 90, 180, 270</range> 2817 <details> 2818 The clockwise rotation angle in degrees, relative to the orientation 2819 to the camera, that the JPEG picture needs to be rotated by, to be viewed 2820 upright. 2821 2822 Camera devices may either encode this value into the JPEG EXIF header, or 2823 rotate the image data to match this orientation. 2824 2825 Note that this orientation is relative to the orientation of the camera sensor, given 2826 by android.sensor.orientation. 2827 2828 To translate from the device orientation given by the Android sensor APIs, the following 2829 sample code may be used: 2830 2831 private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) { 2832 if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0; 2833 int sensorOrientation = c.get(CameraCharacteristics.SENSOR_ORIENTATION); 2834 2835 // Round device orientation to a multiple of 90 2836 deviceOrientation = (deviceOrientation + 45) / 90 * 90; 2837 2838 // Reverse device orientation for front-facing cameras 2839 boolean facingFront = c.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_FRONT; 2840 if (facingFront) deviceOrientation = -deviceOrientation; 2841 2842 // Calculate desired JPEG orientation relative to camera orientation to make 2843 // the image upright relative to the device orientation 2844 int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360; 2845 2846 return jpegOrientation; 2847 } 2848 </details> 2849 <tag id="BC" /> 2850 </entry> 2851 <entry name="quality" type="byte" visibility="public" hwlevel="legacy"> 2852 <description>Compression quality of the final JPEG 2853 image.</description> 2854 <range>1-100; larger is higher quality</range> 2855 <details>85-95 is typical usage range.</details> 2856 <tag id="BC" /> 2857 </entry> 2858 <entry name="thumbnailQuality" type="byte" visibility="public" hwlevel="legacy"> 2859 <description>Compression quality of JPEG 2860 thumbnail.</description> 2861 <range>1-100; larger is higher quality</range> 2862 <tag id="BC" /> 2863 </entry> 2864 <entry name="thumbnailSize" type="int32" visibility="public" 2865 container="array" typedef="size" hwlevel="legacy"> 2866 <array> 2867 <size>2</size> 2868 </array> 2869 <description>Resolution of embedded JPEG thumbnail.</description> 2870 <range>android.jpeg.availableThumbnailSizes</range> 2871 <details>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, 2872 but the captured JPEG will still be a valid image. 2873 2874 For best results, when issuing a request for a JPEG image, the thumbnail size selected 2875 should have the same aspect ratio as the main JPEG output. 2876 2877 If the thumbnail image aspect ratio differs from the JPEG primary image aspect 2878 ratio, the camera device creates the thumbnail by cropping it from the primary image. 2879 For example, if the primary image has 4:3 aspect ratio, the thumbnail image has 2880 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to 2881 generate the thumbnail image. The thumbnail image will always have a smaller Field 2882 Of View (FOV) than the primary image when aspect ratios differ. 2883 </details> 2884 <hal_details> 2885 The HAL must not squeeze or stretch the downscaled primary image to generate thumbnail. 2886 The cropping must be done on the primary jpeg image rather than the sensor active array. 2887 The stream cropping rule specified by "S5. Cropping" in camera3.h doesn't apply to the 2888 thumbnail image cropping. 2889 </hal_details> 2890 <tag id="BC" /> 2891 </entry> 2892 </controls> 2893 <static> 2894 <entry name="availableThumbnailSizes" type="int32" visibility="public" 2895 container="array" typedef="size" hwlevel="legacy"> 2896 <array> 2897 <size>2</size> 2898 <size>n</size> 2899 </array> 2900 <description>List of JPEG thumbnail sizes for android.jpeg.thumbnailSize supported by this 2901 camera device.</description> 2902 <details> 2903 This list will include at least one non-zero resolution, plus `(0,0)` for indicating no 2904 thumbnail should be generated. 2905 2906 Below condiditions will be satisfied for this size list: 2907 2908 * The sizes will be sorted by increasing pixel area (width x height). 2909 If several resolutions have the same area, they will be sorted by increasing width. 2910 * The aspect ratio of the largest thumbnail size will be same as the 2911 aspect ratio of largest JPEG output size in android.scaler.availableStreamConfigurations. 2912 The largest size is defined as the size that has the largest pixel area 2913 in a given size list. 2914 * Each output JPEG size in android.scaler.availableStreamConfigurations will have at least 2915 one corresponding size that has the same aspect ratio in availableThumbnailSizes, 2916 and vice versa. 2917 * All non-`(0, 0)` sizes will have non-zero widths and heights.</details> 2918 <tag id="BC" /> 2919 </entry> 2920 <entry name="maxSize" type="int32" visibility="system"> 2921 <description>Maximum size in bytes for the compressed 2922 JPEG buffer</description> 2923 <range>Must be large enough to fit any JPEG produced by 2924 the camera</range> 2925 <details>This is used for sizing the gralloc buffers for 2926 JPEG</details> 2927 </entry> 2928 </static> 2929 <dynamic> 2930 <clone entry="android.jpeg.gpsLocation" kind="controls"> 2931 </clone> 2932 <clone entry="android.jpeg.gpsCoordinates" kind="controls"> 2933 </clone> 2934 <clone entry="android.jpeg.gpsProcessingMethod" 2935 kind="controls"></clone> 2936 <clone entry="android.jpeg.gpsTimestamp" kind="controls"> 2937 </clone> 2938 <clone entry="android.jpeg.orientation" kind="controls"> 2939 </clone> 2940 <clone entry="android.jpeg.quality" kind="controls"> 2941 </clone> 2942 <entry name="size" type="int32"> 2943 <description>The size of the compressed JPEG image, in 2944 bytes</description> 2945 <range>&gt;= 0</range> 2946 <details>If no JPEG output is produced for the request, 2947 this must be 0. 2948 2949 Otherwise, this describes the real size of the compressed 2950 JPEG image placed in the output stream. More specifically, 2951 if android.jpeg.maxSize = 1000000, and a specific capture 2952 has android.jpeg.size = 500000, then the output buffer from 2953 the JPEG stream will be 1000000 bytes, of which the first 2954 500000 make up the real data.</details> 2955 <tag id="FUTURE" /> 2956 </entry> 2957 <clone entry="android.jpeg.thumbnailQuality" 2958 kind="controls"></clone> 2959 <clone entry="android.jpeg.thumbnailSize" kind="controls"> 2960 </clone> 2961 </dynamic> 2962 </section> 2963 <section name="lens"> 2964 <controls> 2965 <entry name="aperture" type="float" visibility="public" hwlevel="full"> 2966 <description>The desired lens aperture size, as a ratio of lens focal length to the 2967 effective aperture diameter.</description> 2968 <units>The f-number (f/N)</units> 2969 <range>android.lens.info.availableApertures</range> 2970 <details>Setting this value is only supported on the camera devices that have a variable 2971 aperture lens. 2972 2973 When this is supported and android.control.aeMode is OFF, 2974 this can be set along with android.sensor.exposureTime, 2975 android.sensor.sensitivity, and android.sensor.frameDuration 2976 to achieve manual exposure control. 2977 2978 The requested aperture value may take several frames to reach the 2979 requested value; the camera device will report the current (intermediate) 2980 aperture size in capture result metadata while the aperture is changing. 2981 While the aperture is still changing, android.lens.state will be set to MOVING. 2982 2983 When this is supported and android.control.aeMode is one of 2984 the ON modes, this will be overridden by the camera device 2985 auto-exposure algorithm, the overridden values are then provided 2986 back to the user in the corresponding result.</details> 2987 <tag id="V1" /> 2988 </entry> 2989 <entry name="filterDensity" type="float" visibility="public" hwlevel="full"> 2990 <description> 2991 The desired setting for the lens neutral density filter(s). 2992 </description> 2993 <units>Exposure Value (EV)</units> 2994 <range>android.lens.info.availableFilterDensities</range> 2995 <details> 2996 This control will not be supported on most camera devices. 2997 2998 Lens filters are typically used to lower the amount of light the 2999 sensor is exposed to (measured in steps of EV). As used here, an EV 3000 step is the standard logarithmic representation, which are 3001 non-negative, and inversely proportional to the amount of light 3002 hitting the sensor. For example, setting this to 0 would result 3003 in no reduction of the incoming light, and setting this to 2 would 3004 mean that the filter is set to reduce incoming light by two stops 3005 (allowing 1/4 of the prior amount of light to the sensor). 3006 3007 It may take several frames before the lens filter density changes 3008 to the requested value. While the filter density is still changing, 3009 android.lens.state will be set to MOVING. 3010 </details> 3011 <tag id="V1" /> 3012 </entry> 3013 <entry name="focalLength" type="float" visibility="public" hwlevel="legacy"> 3014 <description> 3015 The desired lens focal length; used for optical zoom. 3016 </description> 3017 <units>Millimeters</units> 3018 <range>android.lens.info.availableFocalLengths</range> 3019 <details> 3020 This setting controls the physical focal length of the camera 3021 device's lens. Changing the focal length changes the field of 3022 view of the camera device, and is usually used for optical zoom. 3023 3024 Like android.lens.focusDistance and android.lens.aperture, this 3025 setting won't be applied instantaneously, and it may take several 3026 frames before the lens can change to the requested focal length. 3027 While the focal length is still changing, android.lens.state will 3028 be set to MOVING. 3029 3030 Optical zoom will not be supported on most devices. 3031 </details> 3032 <tag id="V1" /> 3033 </entry> 3034 <entry name="focusDistance" type="float" visibility="public" hwlevel="full"> 3035 <description>Desired distance to plane of sharpest focus, 3036 measured from frontmost surface of the lens.</description> 3037 <units>See android.lens.info.focusDistanceCalibration for details</units> 3038 <range>&gt;= 0</range> 3039 <details> 3040 This control can be used for setting manual focus, on devices that support 3041 the MANUAL_SENSOR capability and have a variable-focus lens (see 3042 android.lens.info.minimumFocusDistance). 3043 3044 A value of `0.0f` means infinity focus. The value set will be clamped to 3045 `[0.0f, android.lens.info.minimumFocusDistance]`. 3046 3047 Like android.lens.focalLength, this setting won't be applied 3048 instantaneously, and it may take several frames before the lens 3049 can move to the requested focus distance. While the lens is still moving, 3050 android.lens.state will be set to MOVING. 3051 3052 LEGACY devices support at most setting this to `0.0f` 3053 for infinity focus. 3054 </details> 3055 <tag id="BC" /> 3056 <tag id="V1" /> 3057 </entry> 3058 <entry name="opticalStabilizationMode" type="byte" visibility="public" 3059 enum="true" hwlevel="limited"> 3060 <enum> 3061 <value>OFF 3062 <notes>Optical stabilization is unavailable.</notes> 3063 </value> 3064 <value optional="true">ON 3065 <notes>Optical stabilization is enabled.</notes> 3066 </value> 3067 </enum> 3068 <description> 3069 Sets whether the camera device uses optical image stabilization (OIS) 3070 when capturing images. 3071 </description> 3072 <range>android.lens.info.availableOpticalStabilization</range> 3073 <details> 3074 OIS is used to compensate for motion blur due to small 3075 movements of the camera during capture. Unlike digital image 3076 stabilization (android.control.videoStabilizationMode), OIS 3077 makes use of mechanical elements to stabilize the camera 3078 sensor, and thus allows for longer exposure times before 3079 camera shake becomes apparent. 3080 3081 Switching between different optical stabilization modes may take several 3082 frames to initialize, the camera device will report the current mode in 3083 capture result metadata. For example, When "ON" mode is requested, the 3084 optical stabilization modes in the first several capture results may still 3085 be "OFF", and it will become "ON" when the initialization is done. 3086 3087 If a camera device supports both OIS and digital image stabilization 3088 (android.control.videoStabilizationMode), turning both modes on may produce undesirable 3089 interaction, so it is recommended not to enable both at the same time. 3090 3091 Not all devices will support OIS; see 3092 android.lens.info.availableOpticalStabilization for 3093 available controls. 3094 </details> 3095 <tag id="V1" /> 3096 </entry> 3097 </controls> 3098 <static> 3099 <namespace name="info"> 3100 <entry name="availableApertures" type="float" visibility="public" 3101 container="array" hwlevel="full"> 3102 <array> 3103 <size>n</size> 3104 </array> 3105 <description>List of aperture size values for android.lens.aperture that are 3106 supported by this camera device.</description> 3107 <units>The aperture f-number</units> 3108 <details>If the camera device doesn't support a variable lens aperture, 3109 this list will contain only one value, which is the fixed aperture size. 3110 3111 If the camera device supports a variable aperture, the aperture values 3112 in this list will be sorted in ascending order.</details> 3113 <tag id="V1" /> 3114 </entry> 3115 <entry name="availableFilterDensities" type="float" visibility="public" 3116 container="array" hwlevel="full"> 3117 <array> 3118 <size>n</size> 3119 </array> 3120 <description> 3121 List of neutral density filter values for 3122 android.lens.filterDensity that are supported by this camera device. 3123 </description> 3124 <units>Exposure value (EV)</units> 3125 <range> 3126 Values are &gt;= 0 3127 </range> 3128 <details> 3129 If a neutral density filter is not supported by this camera device, 3130 this list will contain only 0. Otherwise, this list will include every 3131 filter density supported by the camera device, in ascending order. 3132 </details> 3133 <tag id="V1" /> 3134 </entry> 3135 <entry name="availableFocalLengths" type="float" visibility="public" 3136 type_notes="The list of available focal lengths" 3137 container="array" hwlevel="legacy"> 3138 <array> 3139 <size>n</size> 3140 </array> 3141 <description> 3142 List of focal lengths for android.lens.focalLength that are supported by this camera 3143 device. 3144 </description> 3145 <units>Millimeters</units> 3146 <range> 3147 Values are &gt; 0 3148 </range> 3149 <details> 3150 If optical zoom is not supported, this list will only contain 3151 a single value corresponding to the fixed focal length of the 3152 device. Otherwise, this list will include every focal length supported 3153 by the camera device, in ascending order. 3154 </details> 3155 <tag id="BC" /> 3156 <tag id="V1" /> 3157 </entry> 3158 <entry name="availableOpticalStabilization" type="byte" 3159 visibility="public" type_notes="list of enums" container="array" 3160 typedef="enumList" hwlevel="limited"> 3161 <array> 3162 <size>n</size> 3163 </array> 3164 <description> 3165 List of optical image stabilization (OIS) modes for 3166 android.lens.opticalStabilizationMode that are supported by this camera device. 3167 </description> 3168 <range>Any value listed in android.lens.opticalStabilizationMode</range> 3169 <details> 3170 If OIS is not supported by a given camera device, this list will 3171 contain only OFF. 3172 </details> 3173 <tag id="V1" /> 3174 </entry> 3175 <entry name="hyperfocalDistance" type="float" visibility="public" optional="true" 3176 hwlevel="limited"> 3177 <description>Hyperfocal distance for this lens.</description> 3178 <units>See android.lens.info.focusDistanceCalibration for details</units> 3179 <range>If lens is fixed focus, &gt;= 0. If lens has focuser unit, the value is 3180 within `(0.0f, android.lens.info.minimumFocusDistance]`</range> 3181 <details> 3182 If the lens is not fixed focus, the camera device will report this 3183 field when android.lens.info.focusDistanceCalibration is APPROXIMATE or CALIBRATED. 3184 </details> 3185 </entry> 3186 <entry name="minimumFocusDistance" type="float" visibility="public" optional="true" 3187 hwlevel="limited"> 3188 <description>Shortest distance from frontmost surface 3189 of the lens that can be brought into sharp focus.</description> 3190 <units>See android.lens.info.focusDistanceCalibration for details</units> 3191 <range>&gt;= 0</range> 3192 <details>If the lens is fixed-focus, this will be 3193 0.</details> 3194 <hal_details>Mandatory for FULL devices; LIMITED devices 3195 must always set this value to 0 for fixed-focus; and may omit 3196 the minimum focus distance otherwise. 3197 3198 This field is also mandatory for all devices advertising 3199 the MANUAL_SENSOR capability.</hal_details> 3200 <tag id="V1" /> 3201 </entry> 3202 <entry name="shadingMapSize" type="int32" visibility="hidden" 3203 type_notes="width and height (N, M) of lens shading map provided by the camera device." 3204 container="array" typedef="size" hwlevel="full"> 3205 <array> 3206 <size>2</size> 3207 </array> 3208 <description>Dimensions of lens shading map.</description> 3209 <range>Both values &gt;= 1</range> 3210 <details> 3211 The map should be on the order of 30-40 rows and columns, and 3212 must be smaller than 64x64. 3213 </details> 3214 <tag id="V1" /> 3215 </entry> 3216 <entry name="focusDistanceCalibration" type="byte" visibility="public" 3217 enum="true" hwlevel="limited"> 3218 <enum> 3219 <value>UNCALIBRATED 3220 <notes> 3221 The lens focus distance is not accurate, and the units used for 3222 android.lens.focusDistance do not correspond to any physical units. 3223 3224 Setting the lens to the same focus distance on separate occasions may 3225 result in a different real focus distance, depending on factors such 3226 as the orientation of the device, the age of the focusing mechanism, 3227 and the device temperature. The focus distance value will still be 3228 in the range of `[0, android.lens.info.minimumFocusDistance]`, where 0 3229 represents the farthest focus. 3230 </notes> 3231 </value> 3232 <value>APPROXIMATE 3233 <notes> 3234 The lens focus distance is measured in diopters. 3235 3236 However, setting the lens to the same focus distance 3237 on separate occasions may result in a different real 3238 focus distance, depending on factors such as the 3239 orientation of the device, the age of the focusing 3240 mechanism, and the device temperature. 3241 </notes> 3242 </value> 3243 <value>CALIBRATED 3244 <notes> 3245 The lens focus distance is measured in diopters, and 3246 is calibrated. 3247 3248 The lens mechanism is calibrated so that setting the 3249 same focus distance is repeatable on multiple 3250 occasions with good accuracy, and the focus distance 3251 corresponds to the real physical distance to the plane 3252 of best focus. 3253 </notes> 3254 </value> 3255 </enum> 3256 <description>The lens focus distance calibration quality.</description> 3257 <details> 3258 The lens focus distance calibration quality determines the reliability of 3259 focus related metadata entries, i.e. android.lens.focusDistance, 3260 android.lens.focusRange, android.lens.info.hyperfocalDistance, and 3261 android.lens.info.minimumFocusDistance. 3262 3263 APPROXIMATE and CALIBRATED devices report the focus metadata in 3264 units of diopters (1/meter), so `0.0f` represents focusing at infinity, 3265 and increasing positive numbers represent focusing closer and closer 3266 to the camera device. The focus distance control also uses diopters 3267 on these devices. 3268 3269 UNCALIBRATED devices do not use units that are directly comparable 3270 to any real physical measurement, but `0.0f` still represents farthest 3271 focus, and android.lens.info.minimumFocusDistance represents the 3272 nearest focus the device can achieve. 3273 </details> 3274 <hal_details> 3275 For devices advertise APPROXIMATE quality or higher, diopters 0 (infinity 3276 focus) must work. When autofocus is disabled (android.control.afMode == OFF) 3277 and the lens focus distance is set to 0 diopters 3278 (android.lens.focusDistance == 0), the lens will move to focus at infinity 3279 and is stably focused at infinity even if the device tilts. It may take the 3280 lens some time to move; during the move the lens state should be MOVING and 3281 the output diopter value should be changing toward 0. 3282 </hal_details> 3283 <tag id="V1" /> 3284 </entry> 3285 </namespace> 3286 <entry name="facing" type="byte" visibility="public" enum="true" hwlevel="legacy"> 3287 <enum> 3288 <value>FRONT 3289 <notes> 3290 The camera device faces the same direction as the device's screen. 3291 </notes></value> 3292 <value>BACK 3293 <notes> 3294 The camera device faces the opposite direction as the device's screen. 3295 </notes></value> 3296 </enum> 3297 <description>Direction the camera faces relative to 3298 device screen.</description> 3299 </entry> 3300 <entry name="opticalAxisAngle" type="float" 3301 type_notes="degrees. First defines the angle of separation between the perpendicular to the screen and the camera optical axis. The second then defines the clockwise rotation of the optical axis from native device up." 3302 container="array"> 3303 <array> 3304 <size>2</size> 3305 </array> 3306 <description>Relative angle of camera optical axis to the 3307 perpendicular axis from the display</description> 3308 <range>[0-90) for first angle, [0-360) for second</range> 3309 <details>Examples: 3310 3311 (0,0) means that the camera optical axis 3312 is perpendicular to the display surface; 3313 3314 (45,0) means that the camera points 45 degrees up when 3315 device is held upright; 3316 3317 (45,90) means the camera points 45 degrees to the right when 3318 the device is held upright. 3319 3320 Use FACING field to determine perpendicular outgoing 3321 direction</details> 3322 <tag id="FUTURE" /> 3323 </entry> 3324 <entry name="position" type="float" container="array"> 3325 <array> 3326 <size>3, location in mm, in the sensor coordinate 3327 system</size> 3328 </array> 3329 <description>Coordinates of camera optical axis on 3330 device</description> 3331 <tag id="FUTURE" /> 3332 </entry> 3333 </static> 3334 <dynamic> 3335 <clone entry="android.lens.aperture" kind="controls"> 3336 <tag id="V1" /> 3337 </clone> 3338 <clone entry="android.lens.filterDensity" kind="controls"> 3339 <tag id="V1" /> 3340 </clone> 3341 <clone entry="android.lens.focalLength" kind="controls"> 3342 <tag id="BC" /> 3343 </clone> 3344 <clone entry="android.lens.focusDistance" kind="controls"> 3345 <details>Should be zero for fixed-focus cameras</details> 3346 <tag id="BC" /> 3347 </clone> 3348 <entry name="focusRange" type="float" visibility="public" 3349 type_notes="Range of scene distances that are in focus" 3350 container="array" typedef="pairFloatFloat" hwlevel="limited"> 3351 <array> 3352 <size>2</size> 3353 </array> 3354 <description>The range of scene distances that are in 3355 sharp focus (depth of field).</description> 3356 <units>A pair of focus distances in diopters: (near, 3357 far); see android.lens.info.focusDistanceCalibration for details.</units> 3358 <range>&gt;=0</range> 3359 <details>If variable focus not supported, can still report 3360 fixed depth of field range</details> 3361 <tag id="BC" /> 3362 </entry> 3363 <clone entry="android.lens.opticalStabilizationMode" 3364 kind="controls"> 3365 <tag id="V1" /> 3366 </clone> 3367 <entry name="state" type="byte" visibility="public" enum="true" hwlevel="limited"> 3368 <enum> 3369 <value>STATIONARY 3370 <notes> 3371 The lens parameters (android.lens.focalLength, android.lens.focusDistance, 3372 android.lens.filterDensity and android.lens.aperture) are not changing. 3373 </notes> 3374 </value> 3375 <value>MOVING 3376 <notes> 3377 One or several of the lens parameters 3378 (android.lens.focalLength, android.lens.focusDistance, 3379 android.lens.filterDensity or android.lens.aperture) is 3380 currently changing. 3381 </notes> 3382 </value> 3383 </enum> 3384 <description>Current lens status.</description> 3385 <details> 3386 For lens parameters android.lens.focalLength, android.lens.focusDistance, 3387 android.lens.filterDensity and android.lens.aperture, when changes are requested, 3388 they may take several frames to reach the requested values. This state indicates 3389 the current status of the lens parameters. 3390 3391 When the state is STATIONARY, the lens parameters are not changing. This could be 3392 either because the parameters are all fixed, or because the lens has had enough 3393 time to reach the most recently-requested values. 3394 If all these lens parameters are not changable for a camera device, as listed below: 3395 3396 * Fixed focus (`android.lens.info.minimumFocusDistance == 0`), which means 3397 android.lens.focusDistance parameter will always be 0. 3398 * Fixed focal length (android.lens.info.availableFocalLengths contains single value), 3399 which means the optical zoom is not supported. 3400 * No ND filter (android.lens.info.availableFilterDensities contains only 0). 3401 * Fixed aperture (android.lens.info.availableApertures contains single value). 3402 3403 Then this state will always be STATIONARY. 3404 3405 When the state is MOVING, it indicates that at least one of the lens parameters 3406 is changing. 3407 </details> 3408 <tag id="V1" /> 3409 </entry> 3410 </dynamic> 3411 </section> 3412 <section name="noiseReduction"> 3413 <controls> 3414 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 3415 <enum> 3416 <value>OFF 3417 <notes>No noise reduction is applied.</notes></value> 3418 <value>FAST 3419 <notes>Noise reduction is applied without reducing frame rate relative to sensor 3420 output.</notes></value> 3421 <value>HIGH_QUALITY 3422 <notes>High-quality noise reduction is applied, at the cost of reducing frame rate 3423 relative to sensor output.</notes></value> 3424 </enum> 3425 <description>Mode of operation for the noise reduction algorithm.</description> 3426 <range>android.noiseReduction.availableNoiseReductionModes</range> 3427 <details>The noise reduction algorithm attempts to improve image quality by removing 3428 excessive noise added by the capture process, especially in dark conditions. 3429 OFF means no noise reduction will be applied by the camera device. 3430 3431 FAST/HIGH_QUALITY both mean camera device determined noise filtering 3432 will be applied. HIGH_QUALITY mode indicates that the camera device 3433 will use the highest-quality noise filtering algorithms, 3434 even if it slows down capture rate. FAST means the camera device will not 3435 slow down capture rate when applying noise filtering. 3436 </details> 3437 <tag id="V1" /> 3438 </entry> 3439 <entry name="strength" type="byte"> 3440 <description>Control the amount of noise reduction 3441 applied to the images</description> 3442 <units>1-10; 10 is max noise reduction</units> 3443 <range>1 - 10</range> 3444 <tag id="FUTURE" /> 3445 </entry> 3446 </controls> 3447 <static> 3448 <entry name="availableNoiseReductionModes" type="byte" visibility="public" 3449 type_notes="list of enums" container="array" typedef="enumList" hwlevel="limited"> 3450 <array> 3451 <size>n</size> 3452 </array> 3453 <description> 3454 List of noise reduction modes for android.noiseReduction.mode that are supported 3455 by this camera device. 3456 </description> 3457 <range>Any value listed in android.noiseReduction.mode</range> 3458 <details> 3459 Full-capability camera devices will always support OFF and FAST. 3460 3461 Legacy-capability camera devices will only support FAST mode. 3462 </details> 3463 <tag id="V1" /> 3464 </entry> 3465 </static> 3466 <dynamic> 3467 <clone entry="android.noiseReduction.mode" kind="controls"> 3468 <tag id="V1" /> 3469 </clone> 3470 </dynamic> 3471 </section> 3472 <section name="quirks"> 3473 <static> 3474 <entry name="meteringCropRegion" type="byte" visibility="system" deprecated="true" optional="true"> 3475 <description>If set to 1, the camera service does not 3476 scale 'normalized' coordinates with respect to the crop 3477 region. This applies to metering input (a{e,f,wb}Region 3478 and output (face rectangles).</description> 3479 <details>Normalized coordinates refer to those in the 3480 (-1000,1000) range mentioned in the 3481 android.hardware.Camera API. 3482 3483 HAL implementations should instead always use and emit 3484 sensor array-relative coordinates for all region data. Does 3485 not need to be listed in static metadata. Support will be 3486 removed in future versions of camera service.</details> 3487 </entry> 3488 <entry name="triggerAfWithAuto" type="byte" visibility="system" deprecated="true" optional="true"> 3489 <description>If set to 1, then the camera service always 3490 switches to FOCUS_MODE_AUTO before issuing a AF 3491 trigger.</description> 3492 <details>HAL implementations should implement AF trigger 3493 modes for AUTO, MACRO, CONTINUOUS_FOCUS, and 3494 CONTINUOUS_PICTURE modes instead of using this flag. Does 3495 not need to be listed in static metadata. Support will be 3496 removed in future versions of camera service</details> 3497 </entry> 3498 <entry name="useZslFormat" type="byte" visibility="system" deprecated="true" optional="true"> 3499 <description>If set to 1, the camera service uses 3500 CAMERA2_PIXEL_FORMAT_ZSL instead of 3501 HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED for the zero 3502 shutter lag stream</description> 3503 <details>HAL implementations should use gralloc usage flags 3504 to determine that a stream will be used for 3505 zero-shutter-lag, instead of relying on an explicit 3506 format setting. Does not need to be listed in static 3507 metadata. Support will be removed in future versions of 3508 camera service.</details> 3509 </entry> 3510 <entry name="usePartialResult" type="byte" visibility="hidden" deprecated="true" optional="true"> 3511 <description> 3512 If set to 1, the HAL will always split result 3513 metadata for a single capture into multiple buffers, 3514 returned using multiple process_capture_result calls. 3515 </description> 3516 <details> 3517 Does not need to be listed in static 3518 metadata. Support for partial results will be reworked in 3519 future versions of camera service. This quirk will stop 3520 working at that point; DO NOT USE without careful 3521 consideration of future support. 3522 </details> 3523 <hal_details> 3524 Refer to `camera3_capture_result::partial_result` 3525 for information on how to implement partial results. 3526 </hal_details> 3527 </entry> 3528 </static> 3529 <dynamic> 3530 <entry name="partialResult" type="byte" visibility="hidden" deprecated="true" optional="true" enum="true" typedef="boolean"> 3531 <enum> 3532 <value>FINAL 3533 <notes>The last or only metadata result buffer 3534 for this capture.</notes> 3535 </value> 3536 <value>PARTIAL 3537 <notes>A partial buffer of result metadata for this 3538 capture. More result buffers for this capture will be sent 3539 by the camera device, the last of which will be marked 3540 FINAL.</notes> 3541 </value> 3542 </enum> 3543 <description> 3544 Whether a result given to the framework is the 3545 final one for the capture, or only a partial that contains a 3546 subset of the full set of dynamic metadata 3547 values.</description> 3548 <range>Optional. Default value is FINAL.</range> 3549 <details> 3550 The entries in the result metadata buffers for a 3551 single capture may not overlap, except for this entry. The 3552 FINAL buffers must retain FIFO ordering relative to the 3553 requests that generate them, so the FINAL buffer for frame 3 must 3554 always be sent to the framework after the FINAL buffer for frame 2, and 3555 before the FINAL buffer for frame 4. PARTIAL buffers may be returned 3556 in any order relative to other frames, but all PARTIAL buffers for a given 3557 capture must arrive before the FINAL buffer for that capture. This entry may 3558 only be used by the camera device if quirks.usePartialResult is set to 1. 3559 </details> 3560 <hal_details> 3561 Refer to `camera3_capture_result::partial_result` 3562 for information on how to implement partial results. 3563 </hal_details> 3564 </entry> 3565 </dynamic> 3566 </section> 3567 <section name="request"> 3568 <controls> 3569 <entry name="frameCount" type="int32" visibility="system" deprecated="true"> 3570 <description>A frame counter set by the framework. Must 3571 be maintained unchanged in output frame. This value monotonically 3572 increases with every new result (that is, each new result has a unique 3573 frameCount value). 3574 </description> 3575 <units>incrementing integer</units> 3576 <range>Any int.</range> 3577 </entry> 3578 <entry name="id" type="int32" visibility="hidden"> 3579 <description>An application-specified ID for the current 3580 request. Must be maintained unchanged in output 3581 frame</description> 3582 <units>arbitrary integer assigned by application</units> 3583 <range>Any int</range> 3584 <tag id="V1" /> 3585 </entry> 3586 <entry name="inputStreams" type="int32" visibility="system" deprecated="true" 3587 container="array"> 3588 <array> 3589 <size>n</size> 3590 </array> 3591 <description>List which camera reprocess stream is used 3592 for the source of reprocessing data.</description> 3593 <units>List of camera reprocess stream IDs</units> 3594 <range> 3595 Typically, only one entry allowed, must be a valid reprocess stream ID. 3596 </range> 3597 <details>Only meaningful when android.request.type == 3598 REPROCESS. Ignored otherwise</details> 3599 <tag id="HAL2" /> 3600 </entry> 3601 <entry name="metadataMode" type="byte" visibility="system" 3602 enum="true"> 3603 <enum> 3604 <value>NONE 3605 <notes>No metadata should be produced on output, except 3606 for application-bound buffer data. If no 3607 application-bound streams exist, no frame should be 3608 placed in the output frame queue. If such streams 3609 exist, a frame should be placed on the output queue 3610 with null metadata but with the necessary output buffer 3611 information. Timestamp information should still be 3612 included with any output stream buffers</notes></value> 3613 <value>FULL 3614 <notes>All metadata should be produced. Statistics will 3615 only be produced if they are separately 3616 enabled</notes></value> 3617 </enum> 3618 <description>How much metadata to produce on 3619 output</description> 3620 <tag id="FUTURE" /> 3621 </entry> 3622 <entry name="outputStreams" type="int32" visibility="system" deprecated="true" 3623 container="array"> 3624 <array> 3625 <size>n</size> 3626 </array> 3627 <description>Lists which camera output streams image data 3628 from this capture must be sent to</description> 3629 <units>List of camera stream IDs</units> 3630 <range>List must only include streams that have been 3631 created</range> 3632 <details>If no output streams are listed, then the image 3633 data should simply be discarded. The image data must 3634 still be captured for metadata and statistics production, 3635 and the lens and flash must operate as requested.</details> 3636 <tag id="HAL2" /> 3637 </entry> 3638 <entry name="type" type="byte" visibility="system" deprecated="true" enum="true"> 3639 <enum> 3640 <value>CAPTURE 3641 <notes>Capture a new image from the imaging hardware, 3642 and process it according to the 3643 settings</notes></value> 3644 <value>REPROCESS 3645 <notes>Process previously captured data; the 3646 android.request.inputStreams parameter determines the 3647 source reprocessing stream. TODO: Mark dynamic metadata 3648 needed for reprocessing with [RP]</notes></value> 3649 </enum> 3650 <description>The type of the request; either CAPTURE or 3651 REPROCESS. For HAL3, this tag is redundant. 3652 </description> 3653 <tag id="HAL2" /> 3654 </entry> 3655 </controls> 3656 <static> 3657 <entry name="maxNumOutputStreams" type="int32" visibility="hidden" 3658 container="array" hwlevel="legacy"> 3659 <array> 3660 <size>3</size> 3661 </array> 3662 <description>The maximum numbers of different types of output streams 3663 that can be configured and used simultaneously by a camera device. 3664 </description> 3665 <range> 3666 For processed (and stalling) format streams, &gt;= 1. 3667 3668 For Raw format (either stalling or non-stalling) streams, &gt;= 0. 3669 3670 For processed (but not stalling) format streams, &gt;= 3 3671 for FULL mode devices (`android.info.supportedHardwareLevel == FULL`); 3672 &gt;= 2 for LIMITED mode devices (`android.info.supportedHardwareLevel == LIMITED`). 3673 </range> 3674 <details> 3675 This is a 3 element tuple that contains the max number of output simultaneous 3676 streams for raw sensor, processed (but not stalling), and processed (and stalling) 3677 formats respectively. For example, assuming that JPEG is typically a processed and 3678 stalling stream, if max raw sensor format output stream number is 1, max YUV streams 3679 number is 3, and max JPEG stream number is 2, then this tuple should be `(1, 3, 2)`. 3680 3681 This lists the upper bound of the number of output streams supported by 3682 the camera device. Using more streams simultaneously may require more hardware and 3683 CPU resources that will consume more power. The image format for an output stream can 3684 be any supported format provided by android.scaler.availableStreamConfigurations. 3685 The formats defined in android.scaler.availableStreamConfigurations can be catergorized 3686 into the 3 stream types as below: 3687 3688 * Processed (but stalling): any non-RAW format with a stallDurations &gt; 0. 3689 Typically JPEG format (ImageFormat#JPEG). 3690 * Raw formats: ImageFormat#RAW_SENSOR, ImageFormat#RAW10 and ImageFormat#RAW_OPAQUE. 3691 * Processed (but not-stalling): any non-RAW format without a stall duration. 3692 Typically ImageFormat#YUV_420_888, ImageFormat#NV21, ImageFormat#YV12. 3693 </details> 3694 <tag id="BC" /> 3695 </entry> 3696 <entry name="maxNumOutputRaw" type="int32" visibility="public" synthetic="true" hwlevel="legacy"> 3697 <description>The maximum numbers of different types of output streams 3698 that can be configured and used simultaneously by a camera device 3699 for any `RAW` formats. 3700 </description> 3701 <range> 3702 &gt;= 0 3703 </range> 3704 <details> 3705 This value contains the max number of output simultaneous 3706 streams from the raw sensor. 3707 3708 This lists the upper bound of the number of output streams supported by 3709 the camera device. Using more streams simultaneously may require more hardware and 3710 CPU resources that will consume more power. The image format for this kind of an output stream can 3711 be any `RAW` and supported format provided by android.scaler.streamConfigurationMap. 3712 3713 In particular, a `RAW` format is typically one of: 3714 3715 * ImageFormat#RAW_SENSOR 3716 * ImageFormat#RAW10 3717 * Opaque `RAW` 3718 3719 LEGACY mode devices (android.info.supportedHardwareLevel `==` LEGACY) 3720 never support raw streams. 3721 </details> 3722 </entry> 3723 <entry name="maxNumOutputProc" type="int32" visibility="public" synthetic="true" hwlevel="legacy"> 3724 <description>The maximum numbers of different types of output streams 3725 that can be configured and used simultaneously by a camera device 3726 for any processed (but not-stalling) formats. 3727 </description> 3728 <range> 3729 &gt;= 3 3730 for FULL mode devices (`android.info.supportedHardwareLevel == FULL`); 3731 &gt;= 2 for LIMITED mode devices (`android.info.supportedHardwareLevel == LIMITED`). 3732 </range> 3733 <details> 3734 This value contains the max number of output simultaneous 3735 streams for any processed (but not-stalling) formats. 3736 3737 This lists the upper bound of the number of output streams supported by 3738 the camera device. Using more streams simultaneously may require more hardware and 3739 CPU resources that will consume more power. The image format for this kind of an output stream can 3740 be any non-`RAW` and supported format provided by android.scaler.streamConfigurationMap. 3741 3742 Processed (but not-stalling) is defined as any non-RAW format without a stall duration. 3743 Typically: 3744 3745 * ImageFormat#YUV_420_888 3746 * ImageFormat#NV21 3747 * ImageFormat#YV12 3748 * Implementation-defined formats, i.e. StreamConfiguration#isOutputSupportedFor(Class) 3749 3750 For full guarantees, query StreamConfigurationMap#getOutputStallDuration with 3751 a processed format -- it will return 0 for a non-stalling stream. 3752 3753 LEGACY devices will support at least 2 processing/non-stalling streams. 3754 </details> 3755 </entry> 3756 <entry name="maxNumOutputProcStalling" type="int32" visibility="public" synthetic="true" hwlevel="legacy"> 3757 <description>The maximum numbers of different types of output streams 3758 that can be configured and used simultaneously by a camera device 3759 for any processed (and stalling) formats. 3760 </description> 3761 <range> 3762 &gt;= 1 3763 </range> 3764 <details> 3765 This value contains the max number of output simultaneous 3766 streams for any processed (but not-stalling) formats. 3767 3768 This lists the upper bound of the number of output streams supported by 3769 the camera device. Using more streams simultaneously may require more hardware and 3770 CPU resources that will consume more power. The image format for this kind of an output stream can 3771 be any non-`RAW` and supported format provided by android.scaler.streamConfigurationMap. 3772 3773 A processed and stalling format is defined as any non-RAW format with a stallDurations &gt; 0. 3774 Typically only the `JPEG` format (ImageFormat#JPEG) is a stalling format. 3775 3776 For full guarantees, query StreamConfigurationMap#getOutputStallDuration with 3777 a processed format -- it will return a non-0 value for a stalling stream. 3778 3779 LEGACY devices will support up to 1 processing/stalling stream. 3780 </details> 3781 </entry> 3782 <entry name="maxNumReprocessStreams" type="int32" visibility="system" 3783 deprecated="true" container="array"> 3784 <array> 3785 <size>1</size> 3786 </array> 3787 <description>How many reprocessing streams of any type 3788 can be allocated at the same time.</description> 3789 <range>&gt;= 0</range> 3790 <details> 3791 Only used by HAL2.x. 3792 3793 When set to 0, it means no reprocess stream is supported. 3794 </details> 3795 <tag id="HAL2" /> 3796 </entry> 3797 <entry name="maxNumInputStreams" type="int32" visibility="hidden" hwlevel="full"> 3798 <description> 3799 The maximum numbers of any type of input streams 3800 that can be configured and used simultaneously by a camera device. 3801 </description> 3802 <range> 3803 0 or 1. 3804 </range> 3805 <details>When set to 0, it means no input stream is supported. 3806 3807 The image format for a input stream can be any supported 3808 format provided by 3809 android.scaler.availableInputOutputFormatsMap. When using an 3810 input stream, there must be at least one output stream 3811 configured to to receive the reprocessed images. 3812 3813 For example, for Zero Shutter Lag (ZSL) still capture use case, the input 3814 stream image format will be RAW_OPAQUE, the associated output stream image format 3815 should be JPEG. 3816 </details> 3817 </entry> 3818 </static> 3819 <dynamic> 3820 <entry name="frameCount" type="int32" visibility="hidden" deprecated="true"> 3821 <description>A frame counter set by the framework. This value monotonically 3822 increases with every new result (that is, each new result has a unique 3823 frameCount value).</description> 3824 <units>count of frames</units> 3825 <range>&gt; 0</range> 3826 <details>Reset on release()</details> 3827 </entry> 3828 <clone entry="android.request.id" kind="controls"></clone> 3829 <clone entry="android.request.metadataMode" 3830 kind="controls"></clone> 3831 <clone entry="android.request.outputStreams" 3832 kind="controls"></clone> 3833 <entry name="pipelineDepth" type="byte" visibility="public" hwlevel="legacy"> 3834 <description>Specifies the number of pipeline stages the frame went 3835 through from when it was exposed to when the final completed result 3836 was available to the framework.</description> 3837 <range>&lt;= android.request.pipelineMaxDepth</range> 3838 <details>Depending on what settings are used in the request, and 3839 what streams are configured, the data may undergo less processing, 3840 and some pipeline stages skipped. 3841 3842 See android.request.pipelineMaxDepth for more details. 3843 </details> 3844 <hal_details> 3845 This value must always represent the accurate count of how many 3846 pipeline stages were actually used. 3847 </hal_details> 3848 </entry> 3849 </dynamic> 3850 <static> 3851 <entry name="pipelineMaxDepth" type="byte" visibility="public" hwlevel="legacy"> 3852 <description>Specifies the number of maximum pipeline stages a frame 3853 has to go through from when it's exposed to when it's available 3854 to the framework.</description> 3855 <details>A typical minimum value for this is 2 (one stage to expose, 3856 one stage to readout) from the sensor. The ISP then usually adds 3857 its own stages to do custom HW processing. Further stages may be 3858 added by SW processing. 3859 3860 Depending on what settings are used (e.g. YUV, JPEG) and what 3861 processing is enabled (e.g. face detection), the actual pipeline 3862 depth (specified by android.request.pipelineDepth) may be less than 3863 the max pipeline depth. 3864 3865 A pipeline depth of X stages is equivalent to a pipeline latency of 3866 X frame intervals. 3867 3868 This value will be 8 or less. 3869 </details> 3870 <hal_details> 3871 This value should be 4 or less. 3872 </hal_details> 3873 </entry> 3874 <entry name="partialResultCount" type="int32" visibility="public" optional="true"> 3875 <description>Defines how many sub-components 3876 a result will be composed of. 3877 </description> 3878 <range>&gt;= 1</range> 3879 <details>In order to combat the pipeline latency, partial results 3880 may be delivered to the application layer from the camera device as 3881 soon as they are available. 3882 3883 Optional; defaults to 1. A value of 1 means that partial 3884 results are not supported, and only the final TotalCaptureResult will 3885 be produced by the camera device. 3886 3887 A typical use case for this might be: after requesting an 3888 auto-focus (AF) lock the new AF state might be available 50% 3889 of the way through the pipeline. The camera device could 3890 then immediately dispatch this state via a partial result to 3891 the application, and the rest of the metadata via later 3892 partial results. 3893 </details> 3894 </entry> 3895 <entry name="availableCapabilities" type="byte" visibility="public" 3896 enum="true" container="array" hwlevel="legacy"> 3897 <array> 3898 <size>n</size> 3899 </array> 3900 <enum> 3901 <value>BACKWARD_COMPATIBLE 3902 <notes>The minimal set of capabilities that every camera 3903 device (regardless of android.info.supportedHardwareLevel) 3904 supports. 3905 3906 This capability is listed by all devices, and 3907 indicates that the camera device has a feature set 3908 that's comparable to the baseline requirements for the 3909 older android.hardware.Camera API. 3910 </notes> 3911 </value> 3912 <value optional="true">MANUAL_SENSOR 3913 <notes> 3914 The camera device can be manually controlled (3A algorithms such 3915 as auto-exposure, and auto-focus can be bypassed). 3916 The camera device supports basic manual control of the sensor image 3917 acquisition related stages. This means the following controls are 3918 guaranteed to be supported: 3919 3920 * Manual frame duration control 3921 * android.sensor.frameDuration 3922 * android.sensor.info.maxFrameDuration 3923 * Manual exposure control 3924 * android.sensor.exposureTime 3925 * android.sensor.info.exposureTimeRange 3926 * Manual sensitivity control 3927 * android.sensor.sensitivity 3928 * android.sensor.info.sensitivityRange 3929 * Manual lens control (if the lens is adjustable) 3930 * android.lens.* 3931 * Manual flash control (if a flash unit is present) 3932 * android.flash.* 3933 * Manual black level locking 3934 * android.blackLevel.lock 3935 3936 If any of the above 3A algorithms are enabled, then the camera 3937 device will accurately report the values applied by 3A in the 3938 result. 3939 3940 A given camera device may also support additional manual sensor controls, 3941 but this capability only covers the above list of controls. 3942 3943 If this is supported, android.scaler.streamConfigurationMap will 3944 additionally return a min frame duration that is greater than 3945 zero for each supported size-format combination. 3946 </notes> 3947 </value> 3948 <value optional="true">MANUAL_POST_PROCESSING 3949 <notes> 3950 The camera device post-processing stages can be manually controlled. 3951 The camera device supports basic manual control of the image post-processing 3952 stages. This means the following controls are guaranteed to be supported: 3953 3954 * Manual tonemap control 3955 * android.tonemap.curve 3956 * android.tonemap.mode 3957 * android.tonemap.maxCurvePoints 3958 * Manual white balance control 3959 * android.colorCorrection.transform 3960 * android.colorCorrection.gains 3961 * Manual lens shading map control 3962 * android.shading.mode 3963 * android.statistics.lensShadingMapMode 3964 * android.statistics.lensShadingMap 3965 * android.lens.info.shadingMapSize 3966 * Manual aberration correction control (if aberration correction is supported) 3967 * android.colorCorrection.aberrationMode 3968 * android.colorCorrection.availableAberrationModes 3969 3970 If auto white balance is enabled, then the camera device 3971 will accurately report the values applied by AWB in the result. 3972 3973 A given camera device may also support additional post-processing 3974 controls, but this capability only covers the above list of controls. 3975 </notes> 3976 </value> 3977 <value optional="true">RAW 3978 <notes> 3979 The camera device supports outputting RAW buffers and 3980 metadata for interpreting them. 3981 3982 Devices supporting the RAW capability allow both for 3983 saving DNG files, and for direct application processing of 3984 raw sensor images. 3985 3986 * RAW_SENSOR is supported as an output format. 3987 * The maximum available resolution for RAW_SENSOR streams 3988 will match either the value in 3989 android.sensor.info.pixelArraySize or 3990 android.sensor.info.activeArraySize. 3991 * All DNG-related optional metadata entries are provided 3992 by the camera device. 3993 </notes> 3994 </value> 3995 <value optional="true" hidden="true">ZSL 3996 <notes> 3997 The camera device supports the Zero Shutter Lag use case. 3998 3999 * At least one input stream can be used. 4000 * RAW_OPAQUE is supported as an output/input format 4001 * Using RAW_OPAQUE does not cause a frame rate drop 4002 relative to the sensor's maximum capture rate (at that 4003 resolution). 4004 * RAW_OPAQUE will be reprocessable into both YUV_420_888 4005 and JPEG formats. 4006 * The maximum available resolution for RAW_OPAQUE streams 4007 (both input/output) will match the maximum available 4008 resolution of JPEG streams. 4009 </notes> 4010 </value> 4011 <value optional="true">READ_SENSOR_SETTINGS 4012 <notes> 4013 The camera device supports accurately reporting the sensor settings for many of 4014 the sensor controls while the built-in 3A algorithm is running. This allows 4015 reporting of sensor settings even when these settings cannot be manually changed. 4016 4017 The values reported for the following controls are guaranteed to be available 4018 in the CaptureResult, including when 3A is enabled: 4019 4020 * Exposure control 4021 * android.sensor.exposureTime 4022 * Sensitivity control 4023 * android.sensor.sensitivity 4024 * Lens controls (if the lens is adjustable) 4025 * android.lens.focusDistance 4026 * android.lens.aperture 4027 4028 This capability is a subset of the MANUAL_SENSOR control capability, and will 4029 always be included if the MANUAL_SENSOR capability is available. 4030 </notes> 4031 </value> 4032 <value optional="true">BURST_CAPTURE 4033 <notes> 4034 The camera device supports capturing maximum-resolution 4035 images at >= 20 frames per second, in at least the 4036 uncompressed YUV format, when post-processing settings 4037 are set to FAST. 4038 4039 More specifically, this means that a size matching the 4040 camera device's active array size is listed as a 4041 supported size for the YUV_420_888 format in 4042 android.scaler.streamConfigurationMap, the minimum frame 4043 duration for that format and size is <= 1/20 s, and 4044 the android.control.aeAvailableTargetFpsRanges entry 4045 lists at least one FPS range where the minimum FPS is 4046 >= 1 / minimumFrameDuration for the maximum-size 4047 YUV_420_888 format. 4048 4049 In addition, the android.sync.maxLatency field is 4050 guaranted to have a value between 0 and 4, inclusive. 4051 </notes> 4052 </value> 4053 </enum> 4054 <description>List of capabilities that this camera device 4055 advertises as fully supporting.</description> 4056 <details> 4057 A capability is a contract that the camera device makes in order 4058 to be able to satisfy one or more use cases. 4059 4060 Listing a capability guarantees that the whole set of features 4061 required to support a common use will all be available. 4062 4063 Using a subset of the functionality provided by an unsupported 4064 capability may be possible on a specific camera device implementation; 4065 to do this query each of android.request.availableRequestKeys, 4066 android.request.availableResultKeys, 4067 android.request.availableCharacteristicsKeys. 4068 4069 The following capabilities are guaranteed to be available on 4070 android.info.supportedHardwareLevel `==` FULL devices: 4071 4072 * MANUAL_SENSOR 4073 * MANUAL_POST_PROCESSING 4074 4075 Other capabilities may be available on either FULL or LIMITED 4076 devices, but the application should query this key to be sure. 4077 </details> 4078 <hal_details> 4079 Additional constraint details per-capability will be available 4080 in the Compatibility Test Suite. 4081 4082 Minimum baseline requirements required for the 4083 BACKWARD_COMPATIBLE capability are not explicitly listed. 4084 Instead refer to "BC" tags and the camera CTS tests in the 4085 android.hardware.camera2.cts package. 4086 4087 Listed controls that can be either request or result (e.g. 4088 android.sensor.exposureTime) must be available both in the 4089 request and the result in order to be considered to be 4090 capability-compliant. 4091 4092 For example, if the HAL claims to support MANUAL control, 4093 then exposure time must be configurable via the request _and_ 4094 the actual exposure applied must be available via 4095 the result. 4096 4097 If MANUAL_SENSOR is omitted, the HAL may choose to omit the 4098 android.scaler.availableMinFrameDurations static property entirely. 4099 </hal_details> 4100 </entry> 4101 <entry name="availableRequestKeys" type="int32" visibility="hidden" 4102 container="array" hwlevel="legacy"> 4103 <array> 4104 <size>n</size> 4105 </array> 4106 <description>A list of all keys that the camera device has available 4107 to use with CaptureRequest.</description> 4108 4109 <details>Attempting to set a key into a CaptureRequest that is not 4110 listed here will result in an invalid request and will be rejected 4111 by the camera device. 4112 4113 This field can be used to query the feature set of a camera device 4114 at a more granular level than capabilities. This is especially 4115 important for optional keys that are not listed under any capability 4116 in android.request.availableCapabilities. 4117 </details> 4118 <hal_details> 4119 Vendor tags must not be listed here. Use the vendor tag metadata 4120 extensions C api instead (refer to camera3.h for more details). 4121 4122 Setting/getting vendor tags will be checked against the metadata 4123 vendor extensions API and not against this field. 4124 4125 The HAL must not consume any request tags that are not listed either 4126 here or in the vendor tag list. 4127 4128 The public camera2 API will always make the vendor tags visible 4129 via CameraCharacteristics#getAvailableCaptureRequestKeys. 4130 </hal_details> 4131 </entry> 4132 <entry name="availableResultKeys" type="int32" visibility="hidden" 4133 container="array" hwlevel="legacy"> 4134 <array> 4135 <size>n</size> 4136 </array> 4137 <description>A list of all keys that the camera device has available 4138 to use with CaptureResult.</description> 4139 4140 <details>Attempting to get a key from a CaptureResult that is not 4141 listed here will always return a `null` value. Getting a key from 4142 a CaptureResult that is listed here will generally never return a `null` 4143 value. 4144 4145 The following keys may return `null` unless they are enabled: 4146 4147 * android.statistics.lensShadingMap (non-null iff android.statistics.lensShadingMapMode == ON) 4148 4149 (Those sometimes-null keys will nevertheless be listed here 4150 if they are available.) 4151 4152 This field can be used to query the feature set of a camera device 4153 at a more granular level than capabilities. This is especially 4154 important for optional keys that are not listed under any capability 4155 in android.request.availableCapabilities. 4156 </details> 4157 <hal_details> 4158 Tags listed here must always have an entry in the result metadata, 4159 even if that size is 0 elements. Only array-type tags (e.g. lists, 4160 matrices, strings) are allowed to have 0 elements. 4161 4162 Vendor tags must not be listed here. Use the vendor tag metadata 4163 extensions C api instead (refer to camera3.h for more details). 4164 4165 Setting/getting vendor tags will be checked against the metadata 4166 vendor extensions API and not against this field. 4167 4168 The HAL must not produce any result tags that are not listed either 4169 here or in the vendor tag list. 4170 4171 The public camera2 API will always make the vendor tags visible 4172 via CameraCharacteristics#getAvailableCaptureResultKeys. 4173 </hal_details> 4174 </entry> 4175 <entry name="availableCharacteristicsKeys" type="int32" visibility="hidden" 4176 container="array" hwlevel="legacy"> 4177 <array> 4178 <size>n</size> 4179 </array> 4180 <description>A list of all keys that the camera device has available 4181 to use with CameraCharacteristics.</description> 4182 <details>This entry follows the same rules as 4183 android.request.availableResultKeys (except that it applies for 4184 CameraCharacteristics instead of CaptureResult). See above for more 4185 details. 4186 </details> 4187 <hal_details> 4188 Keys listed here must always have an entry in the static info metadata, 4189 even if that size is 0 elements. Only array-type tags (e.g. lists, 4190 matrices, strings) are allowed to have 0 elements. 4191 4192 Vendor tags must not be listed here. Use the vendor tag metadata 4193 extensions C api instead (refer to camera3.h for more details). 4194 4195 Setting/getting vendor tags will be checked against the metadata 4196 vendor extensions API and not against this field. 4197 4198 The HAL must not have any tags in its static info that are not listed 4199 either here or in the vendor tag list. 4200 4201 The public camera2 API will always make the vendor tags visible 4202 via CameraCharacteristics#getKeys. 4203 </hal_details> 4204 </entry> 4205 </static> 4206 </section> 4207 <section name="scaler"> 4208 <controls> 4209 <entry name="cropRegion" type="int32" visibility="public" 4210 container="array" typedef="rectangle" hwlevel="legacy"> 4211 <array> 4212 <size>4</size> 4213 </array> 4214 <description>The desired region of the sensor to read out for this capture.</description> 4215 <units>Pixel coordinates relative to 4216 android.sensor.info.activeArraySize</units> 4217 <details> 4218 This control can be used to implement digital zoom. 4219 4220 The crop region coordinate system is based off 4221 android.sensor.info.activeArraySize, with `(0, 0)` being the 4222 top-left corner of the sensor active array. 4223 4224 Output streams use this rectangle to produce their output, 4225 cropping to a smaller region if necessary to maintain the 4226 stream's aspect ratio, then scaling the sensor input to 4227 match the output's configured resolution. 4228 4229 The crop region is applied after the RAW to other color 4230 space (e.g. YUV) conversion. Since raw streams 4231 (e.g. RAW16) don't have the conversion stage, they are not 4232 croppable. The crop region will be ignored by raw streams. 4233 4234 For non-raw streams, any additional per-stream cropping will 4235 be done to maximize the final pixel area of the stream. 4236 4237 For example, if the crop region is set to a 4:3 aspect 4238 ratio, then 4:3 streams will use the exact crop 4239 region. 16:9 streams will further crop vertically 4240 (letterbox). 4241 4242 Conversely, if the crop region is set to a 16:9, then 4:3 4243 outputs will crop horizontally (pillarbox), and 16:9 4244 streams will match exactly. These additional crops will 4245 be centered within the crop region. 4246 4247 The width and height of the crop region cannot 4248 be set to be smaller than 4249 `floor( activeArraySize.width / android.scaler.availableMaxDigitalZoom )` and 4250 `floor( activeArraySize.height / android.scaler.availableMaxDigitalZoom )`, respectively. 4251 4252 The camera device may adjust the crop region to account 4253 for rounding and other hardware requirements; the final 4254 crop region used will be included in the output capture 4255 result. 4256 </details> 4257 <hal_details> 4258 The output streams must maintain square pixels at all 4259 times, no matter what the relative aspect ratios of the 4260 crop region and the stream are. Negative values for 4261 corner are allowed for raw output if full pixel array is 4262 larger than active pixel array. Width and height may be 4263 rounded to nearest larger supportable width, especially 4264 for raw output, where only a few fixed scales may be 4265 possible. 4266 4267 HAL2.x uses only (x, y, width) 4268 </hal_details> 4269 <tag id="BC" /> 4270 </entry> 4271 </controls> 4272 <static> 4273 <entry name="availableFormats" type="int32" 4274 visibility="hidden" deprecated="true" enum="true" 4275 container="array" typedef="imageFormat"> 4276 <array> 4277 <size>n</size> 4278 </array> 4279 <enum> 4280 <value optional="true" id="0x20">RAW16 4281 <notes> 4282 RAW16 is a standard, cross-platform format for raw image 4283 buffers with 16-bit pixels. 4284 4285 Buffers of this format are typically expected to have a 4286 Bayer Color Filter Array (CFA) layout, which is given in 4287 android.sensor.info.colorFilterArrangement. Sensors with 4288 CFAs that are not representable by a format in 4289 android.sensor.info.colorFilterArrangement should not 4290 use this format. 4291 4292 Buffers of this format will also follow the constraints given for 4293 RAW_OPAQUE buffers, but with relaxed performance constraints. 4294 4295 See android.scaler.availableInputOutputFormatsMap for 4296 the full set of performance guarantees. 4297 </notes> 4298 </value> 4299 <value optional="true" id="0x24">RAW_OPAQUE 4300 <notes> 4301 RAW_OPAQUE is a format for raw image buffers coming from an 4302 image sensor. 4303 4304 The actual structure of buffers of this format is 4305 platform-specific, but must follow several constraints: 4306 4307 1. No image post-processing operations may have been applied to 4308 buffers of this type. These buffers contain raw image data coming 4309 directly from the image sensor. 4310 1. If a buffer of this format is passed to the camera device for 4311 reprocessing, the resulting images will be identical to the images 4312 produced if the buffer had come directly from the sensor and was 4313 processed with the same settings. 4314 4315 The intended use for this format is to allow access to the native 4316 raw format buffers coming directly from the camera sensor without 4317 any additional conversions or decrease in framerate. 4318 4319 See android.scaler.availableInputOutputFormatsMap for the full set of 4320 performance guarantees. 4321 </notes> 4322 </value> 4323 <value optional="true" id="0x32315659">YV12 4324 <notes>YCrCb 4:2:0 Planar</notes> 4325 </value> 4326 <value optional="true" id="0x11">YCrCb_420_SP 4327 <notes>NV21</notes> 4328 </value> 4329 <value id="0x22">IMPLEMENTATION_DEFINED 4330 <notes>System internal format, not application-accessible</notes> 4331 </value> 4332 <value id="0x23">YCbCr_420_888 4333 <notes>Flexible YUV420 Format</notes> 4334 </value> 4335 <value id="0x21">BLOB 4336 <notes>JPEG format</notes> 4337 </value> 4338 </enum> 4339 <description>The list of image formats that are supported by this 4340 camera device for output streams.</description> 4341 <details> 4342 All camera devices will support JPEG and YUV_420_888 formats. 4343 4344 When set to YUV_420_888, application can access the YUV420 data directly. 4345 </details> 4346 <hal_details> 4347 These format values are from HAL_PIXEL_FORMAT_* in 4348 system/core/include/system/graphics.h. 4349 4350 When IMPLEMENTATION_DEFINED is used, the platform 4351 gralloc module will select a format based on the usage flags provided 4352 by the camera HAL device and the other endpoint of the stream. It is 4353 usually used by preview and recording streams, where the application doesn't 4354 need access the image data. 4355 4356 YCbCr_420_888 format must be supported by the HAL. When an image stream 4357 needs CPU/application direct access, this format will be used. 4358 4359 The BLOB format must be supported by the HAL. This is used for the JPEG stream. 4360 4361 A RAW_OPAQUE buffer should contain only pixel data. It is strongly 4362 recommended that any information used by the camera device when 4363 processing images is fully expressed by the result metadata 4364 for that image buffer. 4365 </hal_details> 4366 <tag id="BC" /> 4367 </entry> 4368 <entry name="availableJpegMinDurations" type="int64" visibility="hidden" deprecated="true" 4369 container="array"> 4370 <array> 4371 <size>n</size> 4372 </array> 4373 <description>The minimum frame duration that is supported 4374 for each resolution in android.scaler.availableJpegSizes. 4375 </description> 4376 <units>Nanoseconds</units> 4377 <range>TODO: Remove property.</range> 4378 <details> 4379 This corresponds to the minimum steady-state frame duration when only 4380 that JPEG stream is active and captured in a burst, with all 4381 processing (typically in android.*.mode) set to FAST. 4382 4383 When multiple streams are configured, the minimum 4384 frame duration will be &gt;= max(individual stream min 4385 durations)</details> 4386 <tag id="BC" /> 4387 </entry> 4388 <entry name="availableJpegSizes" type="int32" visibility="hidden" 4389 deprecated="true" container="array" typedef="size"> 4390 <array> 4391 <size>n</size> 4392 <size>2</size> 4393 </array> 4394 <description>The JPEG resolutions that are supported by this camera device.</description> 4395 <range>TODO: Remove property.</range> 4396 <details> 4397 The resolutions are listed as `(width, height)` pairs. All camera devices will support 4398 sensor maximum resolution (defined by android.sensor.info.activeArraySize). 4399 </details> 4400 <hal_details> 4401 The HAL must include sensor maximum resolution 4402 (defined by android.sensor.info.activeArraySize), 4403 and should include half/quarter of sensor maximum resolution. 4404 </hal_details> 4405 <tag id="BC" /> 4406 </entry> 4407 <entry name="availableMaxDigitalZoom" type="float" visibility="public" 4408 hwlevel="legacy"> 4409 <description>The maximum ratio between both active area width 4410 and crop region width, and active area height and 4411 crop region height, for android.scaler.cropRegion. 4412 </description> 4413 <units>Zoom scale factor</units> 4414 <range>&gt;=1</range> 4415 <details> 4416 This represents the maximum amount of zooming possible by 4417 the camera device, or equivalently, the minimum cropping 4418 window size. 4419 4420 Crop regions that have a width or height that is smaller 4421 than this ratio allows will be rounded up to the minimum 4422 allowed size by the camera device. 4423 </details> 4424 <tag id="BC" /> 4425 </entry> 4426 <entry name="availableProcessedMinDurations" type="int64" visibility="hidden" deprecated="true" 4427 container="array"> 4428 <array> 4429 <size>n</size> 4430 </array> 4431 <description>For each available processed output size (defined in 4432 android.scaler.availableProcessedSizes), this property lists the 4433 minimum supportable frame duration for that size. 4434 </description> 4435 <units>Nanoseconds</units> 4436 <details> 4437 This should correspond to the frame duration when only that processed 4438 stream is active, with all processing (typically in android.*.mode) 4439 set to FAST. 4440 4441 When multiple streams are configured, the minimum frame duration will 4442 be &gt;= max(individual stream min durations). 4443 </details> 4444 <tag id="BC" /> 4445 </entry> 4446 <entry name="availableProcessedSizes" type="int32" visibility="hidden" 4447 deprecated="true" container="array" typedef="size"> 4448 <array> 4449 <size>n</size> 4450 <size>2</size> 4451 </array> 4452 <description>The resolutions available for use with 4453 processed output streams, such as YV12, NV12, and 4454 platform opaque YUV/RGB streams to the GPU or video 4455 encoders.</description> 4456 <details> 4457 The resolutions are listed as `(width, height)` pairs. 4458 4459 For a given use case, the actual maximum supported resolution 4460 may be lower than what is listed here, depending on the destination 4461 Surface for the image data. For example, for recording video, 4462 the video encoder chosen may have a maximum size limit (e.g. 1080p) 4463 smaller than what the camera (e.g. maximum resolution is 3264x2448) 4464 can provide. 4465 4466 Please reference the documentation for the image data destination to 4467 check if it limits the maximum size for image data. 4468 </details> 4469 <hal_details> 4470 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 4471 the HAL must include all JPEG sizes listed in android.scaler.availableJpegSizes 4472 and each below resolution if it is smaller than or equal to the sensor 4473 maximum resolution (if they are not listed in JPEG sizes already): 4474 4475 * 240p (320 x 240) 4476 * 480p (640 x 480) 4477 * 720p (1280 x 720) 4478 * 1080p (1920 x 1080) 4479 4480 For LIMITED capability devices (`android.info.supportedHardwareLevel == LIMITED`), 4481 the HAL only has to list up to the maximum video size supported by the devices. 4482 </hal_details> 4483 <tag id="BC" /> 4484 </entry> 4485 <entry name="availableRawMinDurations" type="int64" deprecated="true" 4486 container="array"> 4487 <array> 4488 <size>n</size> 4489 </array> 4490 <description> 4491 For each available raw output size (defined in 4492 android.scaler.availableRawSizes), this property lists the minimum 4493 supportable frame duration for that size. 4494 </description> 4495 <units>Nanoseconds</units> 4496 <details> 4497 Should correspond to the frame duration when only the raw stream is 4498 active. 4499 4500 When multiple streams are configured, the minimum 4501 frame duration will be &gt;= max(individual stream min 4502 durations)</details> 4503 <tag id="BC" /> 4504 </entry> 4505 <entry name="availableRawSizes" type="int32" deprecated="true" 4506 container="array" typedef="size"> 4507 <array> 4508 <size>n</size> 4509 <size>2</size> 4510 </array> 4511 <description>The resolutions available for use with raw 4512 sensor output streams, listed as width, 4513 height</description> 4514 </entry> 4515 </static> 4516 <dynamic> 4517 <clone entry="android.scaler.cropRegion" kind="controls"> 4518 </clone> 4519 </dynamic> 4520 <static> 4521 <entry name="availableInputOutputFormatsMap" type="int32" 4522 visibility="hidden" 4523 container="array" typedef="imageFormat" 4524 hwlevel="full"> 4525 <array> 4526 <size>n</size> 4527 </array> 4528 <description>The mapping of image formats that are supported by this 4529 camera device for input streams, to their corresponding output formats. 4530 </description> 4531 <details> 4532 All camera devices with at least 1 4533 android.request.maxNumInputStreams will have at least one 4534 available input format. 4535 4536 The camera device will support the following map of formats, 4537 if its dependent capability is supported: 4538 4539 Input Format | Output Format | Capability 4540 :---------------|:-----------------|:---------- 4541 RAW_OPAQUE | JPEG | ZSL 4542 RAW_OPAQUE | YUV_420_888 | ZSL 4543 RAW_OPAQUE | RAW16 | RAW 4544 RAW16 | YUV_420_888 | RAW 4545 RAW16 | JPEG | RAW 4546 4547 For ZSL-capable camera devices, using the RAW_OPAQUE format 4548 as either input or output will never hurt maximum frame rate (i.e. 4549 StreamConfigurationMap#getOutputStallDuration(int,Size) 4550 for a `format =` RAW_OPAQUE is always 0). 4551 4552 Attempting to configure an input stream with output streams not 4553 listed as available in this map is not valid. 4554 4555 TODO: typedef to ReprocessFormatMap 4556 </details> 4557 <hal_details> 4558 For the formats, see `system/core/include/system/graphics.h` for a definition 4559 of the image format enumerations. 4560 4561 This value is encoded as a variable-size array-of-arrays. 4562 The inner array always contains `[format, length, ...]` where 4563 `...` has `length` elements. An inner array is followed by another 4564 inner array if the total metadata entry size hasn't yet been exceeded. 4565 4566 A code sample to read/write this encoding (with a device that 4567 supports reprocessing RAW_OPAQUE to RAW16, YUV_420_888, and JPEG, 4568 and reprocessing RAW16 to YUV_420_888 and JPEG): 4569 4570 // reading 4571 int32_t* contents = &entry.i32[0]; 4572 for (size_t i = 0; i < entry.count; ) { 4573 int32_t format = contents[i++]; 4574 int32_t length = contents[i++]; 4575 int32_t output_formats[length]; 4576 memcpy(&output_formats[0], &contents[i], 4577 length * sizeof(int32_t)); 4578 i += length; 4579 } 4580 4581 // writing (static example, RAW+ZSL) 4582 int32_t[] contents = { 4583 RAW_OPAQUE, 3, RAW16, YUV_420_888, BLOB, 4584 RAW16, 2, YUV_420_888, BLOB, 4585 }; 4586 update_camera_metadata_entry(metadata, index, &contents[0], 4587 sizeof(contents)/sizeof(contents[0]), &updated_entry); 4588 4589 If the HAL claims to support any of the capabilities listed in the 4590 above details, then it must also support all the input-output 4591 combinations listed for that capability. It can optionally support 4592 additional formats if it so chooses. 4593 4594 Refer to android.scaler.availableFormats for the enum values 4595 which correspond to HAL_PIXEL_FORMAT_* in 4596 system/core/include/system/graphics.h. 4597 </hal_details> 4598 </entry> 4599 <entry name="availableStreamConfigurations" type="int32" visibility="hidden" 4600 enum="true" container="array" 4601 typedef="streamConfiguration" hwlevel="legacy"> 4602 <array> 4603 <size>n</size> 4604 <size>4</size> 4605 </array> 4606 <enum> 4607 <value>OUTPUT</value> 4608 <value>INPUT</value> 4609 </enum> 4610 <description>The available stream configurations that this 4611 camera device supports 4612 (i.e. format, width, height, output/input stream). 4613 </description> 4614 <details> 4615 The configurations are listed as `(format, width, height, input?)` 4616 tuples. 4617 4618 For a given use case, the actual maximum supported resolution 4619 may be lower than what is listed here, depending on the destination 4620 Surface for the image data. For example, for recording video, 4621 the video encoder chosen may have a maximum size limit (e.g. 1080p) 4622 smaller than what the camera (e.g. maximum resolution is 3264x2448) 4623 can provide. 4624 4625 Please reference the documentation for the image data destination to 4626 check if it limits the maximum size for image data. 4627 4628 Not all output formats may be supported in a configuration with 4629 an input stream of a particular format. For more details, see 4630 android.scaler.availableInputOutputFormatsMap. 4631 4632 The following table describes the minimum required output stream 4633 configurations based on the hardware level 4634 (android.info.supportedHardwareLevel): 4635 4636 Format | Size | Hardware Level | Notes 4637 :-------------:|:--------------------------------------------:|:--------------:|:--------------: 4638 JPEG | android.sensor.info.activeArraySize | Any | 4639 JPEG | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 4640 JPEG | 1280x720 (720) | Any | if 720p <= activeArraySize 4641 JPEG | 640x480 (480p) | Any | if 480p <= activeArraySize 4642 JPEG | 320x240 (240p) | Any | if 240p <= activeArraySize 4643 YUV_420_888 | all output sizes available for JPEG | FULL | 4644 YUV_420_888 | all output sizes available for JPEG, up to the maximum video size | LIMITED | 4645 IMPLEMENTATION_DEFINED | same as YUV_420_888 | Any | 4646 4647 Refer to android.request.availableCapabilities for additional 4648 mandatory stream configurations on a per-capability basis. 4649 </details> 4650 <hal_details> 4651 It is recommended (but not mandatory) to also include half/quarter 4652 of sensor maximum resolution for JPEG formats (regardless of hardware 4653 level). 4654 4655 (The following is a rewording of the above required table): 4656 4657 For JPEG format, the sizes may be restricted by below conditions: 4658 4659 * The HAL may choose the aspect ratio of each Jpeg size to be one of well known ones 4660 (e.g. 4:3, 16:9, 3:2 etc.). If the sensor maximum resolution 4661 (defined by android.sensor.info.activeArraySize) has an aspect ratio other than these, 4662 it does not have to be included in the supported JPEG sizes. 4663 * Some hardware JPEG encoders may have pixel boundary alignment requirements, such as 4664 the dimensions being a multiple of 16. 4665 4666 Therefore, the maximum JPEG size may be smaller than sensor maximum resolution. 4667 However, the largest JPEG size must be as close as possible to the sensor maximum 4668 resolution given above constraints. It is required that after aspect ratio adjustments, 4669 additional size reduction due to other issues must be less than 3% in area. For example, 4670 if the sensor maximum resolution is 3280x2464, if the maximum JPEG size has aspect 4671 ratio 4:3, the JPEG encoder alignment requirement is 16, the maximum JPEG size will be 4672 3264x2448. 4673 4674 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 4675 the HAL must include all YUV_420_888 sizes that have JPEG sizes listed 4676 here as output streams. 4677 4678 It must also include each below resolution if it is smaller than or 4679 equal to the sensor maximum resolution (for both YUV_420_888 and JPEG 4680 formats), as output streams: 4681 4682 * 240p (320 x 240) 4683 * 480p (640 x 480) 4684 * 720p (1280 x 720) 4685 * 1080p (1920 x 1080) 4686 4687 For LIMITED capability devices 4688 (`android.info.supportedHardwareLevel == LIMITED`), 4689 the HAL only has to list up to the maximum video size 4690 supported by the device. 4691 4692 Regardless of hardware level, every output resolution available for 4693 YUV_420_888 must also be available for IMPLEMENTATION_DEFINED. 4694 4695 This supercedes the following fields, which are now deprecated: 4696 4697 * availableFormats 4698 * available[Processed,Raw,Jpeg]Sizes 4699 </hal_details> 4700 </entry> 4701 <entry name="availableMinFrameDurations" type="int64" visibility="hidden" 4702 container="array" 4703 typedef="streamConfigurationDuration" hwlevel="legacy"> 4704 <array> 4705 <size>4</size> 4706 <size>n</size> 4707 </array> 4708 <description>This lists the minimum frame duration for each 4709 format/size combination. 4710 </description> 4711 <units>(format, width, height, ns) x n</units> 4712 <details> 4713 This should correspond to the frame duration when only that 4714 stream is active, with all processing (typically in android.*.mode) 4715 set to either OFF or FAST. 4716 4717 When multiple streams are used in a request, the minimum frame 4718 duration will be max(individual stream min durations). 4719 4720 The minimum frame duration of a stream (of a particular format, size) 4721 is the same regardless of whether the stream is input or output. 4722 4723 See android.sensor.frameDuration and 4724 android.scaler.availableStallDurations for more details about 4725 calculating the max frame rate. 4726 4727 (Keep in sync with 4728 StreamConfigurationMap#getOutputMinFrameDuration) 4729 </details> 4730 <tag id="V1" /> 4731 </entry> 4732 <entry name="availableStallDurations" type="int64" visibility="hidden" 4733 container="array" typedef="streamConfigurationDuration" hwlevel="legacy"> 4734 <array> 4735 <size>4</size> 4736 <size>n</size> 4737 </array> 4738 <description>This lists the maximum stall duration for each 4739 format/size combination. 4740 </description> 4741 <units>(format, width, height, ns) x n</units> 4742 <details> 4743 A stall duration is how much extra time would get added 4744 to the normal minimum frame duration for a repeating request 4745 that has streams with non-zero stall. 4746 4747 For example, consider JPEG captures which have the following 4748 characteristics: 4749 4750 * JPEG streams act like processed YUV streams in requests for which 4751 they are not included; in requests in which they are directly 4752 referenced, they act as JPEG streams. This is because supporting a 4753 JPEG stream requires the underlying YUV data to always be ready for 4754 use by a JPEG encoder, but the encoder will only be used (and impact 4755 frame duration) on requests that actually reference a JPEG stream. 4756 * The JPEG processor can run concurrently to the rest of the camera 4757 pipeline, but cannot process more than 1 capture at a time. 4758 4759 In other words, using a repeating YUV request would result 4760 in a steady frame rate (let's say it's 30 FPS). If a single 4761 JPEG request is submitted periodically, the frame rate will stay 4762 at 30 FPS (as long as we wait for the previous JPEG to return each 4763 time). If we try to submit a repeating YUV + JPEG request, then 4764 the frame rate will drop from 30 FPS. 4765 4766 In general, submitting a new request with a non-0 stall time 4767 stream will _not_ cause a frame rate drop unless there are still 4768 outstanding buffers for that stream from previous requests. 4769 4770 Submitting a repeating request with streams (call this `S`) 4771 is the same as setting the minimum frame duration from 4772 the normal minimum frame duration corresponding to `S`, added with 4773 the maximum stall duration for `S`. 4774 4775 If interleaving requests with and without a stall duration, 4776 a request will stall by the maximum of the remaining times 4777 for each can-stall stream with outstanding buffers. 4778 4779 This means that a stalling request will not have an exposure start 4780 until the stall has completed. 4781 4782 This should correspond to the stall duration when only that stream is 4783 active, with all processing (typically in android.*.mode) set to FAST 4784 or OFF. Setting any of the processing modes to HIGH_QUALITY 4785 effectively results in an indeterminate stall duration for all 4786 streams in a request (the regular stall calculation rules are 4787 ignored). 4788 4789 The following formats may always have a stall duration: 4790 4791 * ImageFormat#JPEG 4792 * ImageFormat#RAW_SENSOR 4793 4794 The following formats will never have a stall duration: 4795 4796 * ImageFormat#YUV_420_888 4797 4798 All other formats may or may not have an allowed stall duration on 4799 a per-capability basis; refer to android.request.availableCapabilities 4800 for more details. 4801 4802 See android.sensor.frameDuration for more information about 4803 calculating the max frame rate (absent stalls). 4804 4805 (Keep up to date with 4806 StreamConfigurationMap#getOutputStallDuration(int, Size) ) 4807 </details> 4808 <hal_details> 4809 If possible, it is recommended that all non-JPEG formats 4810 (such as RAW16) should not have a stall duration. RAW10, RAW_OPAQUE and 4811 IMPLEMENTATION_DEFINED must not have stall durations. 4812 </hal_details> 4813 <tag id="V1" /> 4814 </entry> 4815 <entry name="streamConfigurationMap" type="int32" visibility="public" 4816 synthetic="true" typedef="streamConfigurationMap" 4817 hwlevel="legacy"> 4818 <description>The available stream configurations that this 4819 camera device supports; also includes the minimum frame durations 4820 and the stall durations for each format/size combination. 4821 </description> 4822 <details> 4823 All camera devices will support sensor maximum resolution (defined by 4824 android.sensor.info.activeArraySize) for the JPEG format. 4825 4826 For a given use case, the actual maximum supported resolution 4827 may be lower than what is listed here, depending on the destination 4828 Surface for the image data. For example, for recording video, 4829 the video encoder chosen may have a maximum size limit (e.g. 1080p) 4830 smaller than what the camera (e.g. maximum resolution is 3264x2448) 4831 can provide. 4832 4833 Please reference the documentation for the image data destination to 4834 check if it limits the maximum size for image data. 4835 4836 The following table describes the minimum required output stream 4837 configurations based on the hardware level 4838 (android.info.supportedHardwareLevel): 4839 4840 Format | Size | Hardware Level | Notes 4841 :-------------:|:--------------------------------------------:|:--------------:|:--------------: 4842 JPEG | android.sensor.info.activeArraySize | Any | 4843 JPEG | 1920x1080 (1080p) | Any | if 1080p <= activeArraySize 4844 JPEG | 1280x720 (720) | Any | if 720p <= activeArraySize 4845 JPEG | 640x480 (480p) | Any | if 480p <= activeArraySize 4846 JPEG | 320x240 (240p) | Any | if 240p <= activeArraySize 4847 YUV_420_888 | all output sizes available for JPEG | FULL | 4848 YUV_420_888 | all output sizes available for JPEG, up to the maximum video size | LIMITED | 4849 IMPLEMENTATION_DEFINED | same as YUV_420_888 | Any | 4850 4851 Refer to android.request.availableCapabilities for additional 4852 mandatory stream configurations on a per-capability basis. 4853 </details> 4854 <hal_details> 4855 Do not set this property directly 4856 (it is synthetic and will not be available at the HAL layer); 4857 set the android.scaler.availableStreamConfigurations instead. 4858 4859 Not all output formats may be supported in a configuration with 4860 an input stream of a particular format. For more details, see 4861 android.scaler.availableInputOutputFormatsMap. 4862 4863 It is recommended (but not mandatory) to also include half/quarter 4864 of sensor maximum resolution for JPEG formats (regardless of hardware 4865 level). 4866 4867 (The following is a rewording of the above required table): 4868 4869 The HAL must include sensor maximum resolution (defined by 4870 android.sensor.info.activeArraySize). 4871 4872 For FULL capability devices (`android.info.supportedHardwareLevel == FULL`), 4873 the HAL must include all YUV_420_888 sizes that have JPEG sizes listed 4874 here as output streams. 4875 4876 It must also include each below resolution if it is smaller than or 4877 equal to the sensor maximum resolution (for both YUV_420_888 and JPEG 4878 formats), as output streams: 4879 4880 * 240p (320 x 240) 4881 * 480p (640 x 480) 4882 * 720p (1280 x 720) 4883 * 1080p (1920 x 1080) 4884 4885 For LIMITED capability devices 4886 (`android.info.supportedHardwareLevel == LIMITED`), 4887 the HAL only has to list up to the maximum video size 4888 supported by the device. 4889 4890 Regardless of hardware level, every output resolution available for 4891 YUV_420_888 must also be available for IMPLEMENTATION_DEFINED. 4892 4893 This supercedes the following fields, which are now deprecated: 4894 4895 * availableFormats 4896 * available[Processed,Raw,Jpeg]Sizes 4897 </hal_details> 4898 </entry> 4899 <entry name="croppingType" type="byte" visibility="public" enum="true" 4900 hwlevel="legacy"> 4901 <enum> 4902 <value>CENTER_ONLY 4903 <notes> 4904 The camera device only supports centered crop regions. 4905 </notes> 4906 </value> 4907 <value>FREEFORM 4908 <notes> 4909 The camera device supports arbitrarily chosen crop regions. 4910 </notes> 4911 </value> 4912 </enum> 4913 <description>The crop type that this camera device supports.</description> 4914 <details> 4915 When passing a non-centered crop region (android.scaler.cropRegion) to a camera 4916 device that only supports CENTER_ONLY cropping, the camera device will move the 4917 crop region to the center of the sensor active array (android.sensor.info.activeArraySize) 4918 and keep the crop region width and height unchanged. The camera device will return the 4919 final used crop region in metadata result android.scaler.cropRegion. 4920 4921 Camera devices that support FREEFORM cropping will support any crop region that 4922 is inside of the active array. The camera device will apply the same crop region and 4923 return the final used crop region in capture result metadata android.scaler.cropRegion. 4924 4925 FULL capability devices (android.info.supportedHardwareLevel `==` FULL) will support 4926 FREEFORM cropping. LEGACY capability devices will only support CENTER_ONLY cropping. 4927 </details> 4928 </entry> 4929 </static> 4930 </section> 4931 <section name="sensor"> 4932 <controls> 4933 <entry name="exposureTime" type="int64" visibility="public" hwlevel="full"> 4934 <description>Duration each pixel is exposed to 4935 light.</description> 4936 <units>Nanoseconds</units> 4937 <range>android.sensor.info.exposureTimeRange</range> 4938 <details>If the sensor can't expose this exact duration, it will shorten the 4939 duration exposed to the nearest possible value (rather than expose longer). 4940 The final exposure time used will be available in the output capture result. 4941 4942 This control is only effective if android.control.aeMode or android.control.mode is set to 4943 OFF; otherwise the auto-exposure algorithm will override this value. 4944 </details> 4945 <tag id="V1" /> 4946 </entry> 4947 <entry name="frameDuration" type="int64" visibility="public" hwlevel="full"> 4948 <description>Duration from start of frame exposure to 4949 start of next frame exposure.</description> 4950 <units>Nanoseconds</units> 4951 <range>See android.sensor.info.maxFrameDuration, 4952 android.scaler.streamConfigurationMap. The duration 4953 is capped to `max(duration, exposureTime + overhead)`.</range> 4954 <details> 4955 The maximum frame rate that can be supported by a camera subsystem is 4956 a function of many factors: 4957 4958 * Requested resolutions of output image streams 4959 * Availability of binning / skipping modes on the imager 4960 * The bandwidth of the imager interface 4961 * The bandwidth of the various ISP processing blocks 4962 4963 Since these factors can vary greatly between different ISPs and 4964 sensors, the camera abstraction tries to represent the bandwidth 4965 restrictions with as simple a model as possible. 4966 4967 The model presented has the following characteristics: 4968 4969 * The image sensor is always configured to output the smallest 4970 resolution possible given the application's requested output stream 4971 sizes. The smallest resolution is defined as being at least as large 4972 as the largest requested output stream size; the camera pipeline must 4973 never digitally upsample sensor data when the crop region covers the 4974 whole sensor. In general, this means that if only small output stream 4975 resolutions are configured, the sensor can provide a higher frame 4976 rate. 4977 * Since any request may use any or all the currently configured 4978 output streams, the sensor and ISP must be configured to support 4979 scaling a single capture to all the streams at the same time. This 4980 means the camera pipeline must be ready to produce the largest 4981 requested output size without any delay. Therefore, the overall 4982 frame rate of a given configured stream set is governed only by the 4983 largest requested stream resolution. 4984 * Using more than one output stream in a request does not affect the 4985 frame duration. 4986 * Certain format-streams may need to do additional background processing 4987 before data is consumed/produced by that stream. These processors 4988 can run concurrently to the rest of the camera pipeline, but 4989 cannot process more than 1 capture at a time. 4990 4991 The necessary information for the application, given the model above, 4992 is provided via the android.scaler.streamConfigurationMap field 4993 using StreamConfigurationMap#getOutputMinFrameDuration(int, Size). 4994 These are used to determine the maximum frame rate / minimum frame 4995 duration that is possible for a given stream configuration. 4996 4997 Specifically, the application can use the following rules to 4998 determine the minimum frame duration it can request from the camera 4999 device: 5000 5001 1. Let the set of currently configured input/output streams 5002 be called `S`. 5003 1. Find the minimum frame durations for each stream in `S`, by 5004 looking it up in android.scaler.streamConfigurationMap using 5005 StreamConfigurationMap#getOutputMinFrameDuration(int, Size) (with 5006 its respective size/format). Let this set of frame durations be called 5007 `F`. 5008 1. For any given request `R`, the minimum frame duration allowed 5009 for `R` is the maximum out of all values in `F`. Let the streams 5010 used in `R` be called `S_r`. 5011 5012 If none of the streams in `S_r` have a stall time (listed in 5013 StreamConfigurationMap#getOutputStallDuration(int,Size) using its 5014 respective size/format), then the frame duration in 5015 `F` determines the steady state frame rate that the application will 5016 get if it uses `R` as a repeating request. Let this special kind 5017 of request be called `Rsimple`. 5018 5019 A repeating request `Rsimple` can be _occasionally_ interleaved 5020 by a single capture of a new request `Rstall` (which has at least 5021 one in-use stream with a non-0 stall time) and if `Rstall` has the 5022 same minimum frame duration this will not cause a frame rate loss 5023 if all buffers from the previous `Rstall` have already been 5024 delivered. 5025 5026 For more details about stalling, see 5027 StreamConfigurationMap#getOutputStallDuration(int,Size). 5028 5029 This control is only effective if android.control.aeMode or android.control.mode is set to 5030 OFF; otherwise the auto-exposure algorithm will override this value. 5031 </details> 5032 <hal_details> 5033 For more details about stalling, see 5034 android.scaler.availableStallDurations. 5035 </hal_details> 5036 <tag id="V1" /> 5037 </entry> 5038 <entry name="sensitivity" type="int32" visibility="public" hwlevel="full"> 5039 <description>The amount of gain applied to sensor data 5040 before processing.</description> 5041 <units>ISO arithmetic units</units> 5042 <range>android.sensor.info.sensitivityRange</range> 5043 <details> 5044 The sensitivity is the standard ISO sensitivity value, 5045 as defined in ISO 12232:2006. 5046 5047 The sensitivity must be within android.sensor.info.sensitivityRange, and 5048 if if it less than android.sensor.maxAnalogSensitivity, the camera device 5049 is guaranteed to use only analog amplification for applying the gain. 5050 5051 If the camera device cannot apply the exact sensitivity 5052 requested, it will reduce the gain to the nearest supported 5053 value. The final sensitivity used will be available in the 5054 output capture result. 5055 </details> 5056 <hal_details>ISO 12232:2006 REI method is acceptable.</hal_details> 5057 <tag id="V1" /> 5058 </entry> 5059 </controls> 5060 <static> 5061 <namespace name="info"> 5062 <entry name="activeArraySize" type="int32" visibility="public" 5063 type_notes="Four ints defining the active pixel rectangle" 5064 container="array" 5065 typedef="rectangle" 5066 hwlevel="legacy"> 5067 <array> 5068 <size>4</size> 5069 </array> 5070 <description>The area of the image sensor which corresponds to 5071 active pixels.</description> 5072 <units>Pixel coordinates on the image sensor</units> 5073 <range> 5074 </range> 5075 <details> 5076 This is the region of the sensor that actually receives light from the scene. 5077 Therefore, the size of this region determines the maximum field of view and the maximum 5078 number of pixels that an image from this sensor can contain. 5079 5080 The rectangle is defined in terms of the full pixel array; (0,0) is the top-left of the 5081 full pixel array, and the size of the full pixel array is given by 5082 android.sensor.info.pixelArraySize. 5083 5084 Most other keys listing pixel coordinates have their coordinate systems based on the 5085 active array, with `(0, 0)` being the top-left of the active array rectangle. 5086 5087 The active array may be smaller than the full pixel array, since the full array may 5088 include black calibration pixels or other inactive regions. 5089 </details> 5090 <hal_details> 5091 This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be 5092 &gt;= `(0,0)`. 5093 The `(width, height)` must be &lt;= `android.sensor.info.pixelArraySize`. 5094 </hal_details> 5095 <tag id="RAW" /> 5096 </entry> 5097 <entry name="sensitivityRange" type="int32" visibility="public" 5098 type_notes="Range of supported sensitivities" 5099 container="array" typedef="rangeInt" 5100 hwlevel="full"> 5101 <array> 5102 <size>2</size> 5103 </array> 5104 <description>Range of sensitivities for android.sensor.sensitivity supported by this 5105 camera device.</description> 5106 <range>Min <= 100, Max &gt;= 800</range> 5107 <details> 5108 The values are the standard ISO sensitivity values, 5109 as defined in ISO 12232:2006. 5110 </details> 5111 5112 <tag id="BC" /> 5113 <tag id="V1" /> 5114 </entry> 5115 <entry name="colorFilterArrangement" type="byte" visibility="public" enum="true" 5116 hwlevel="full"> 5117 <enum> 5118 <value>RGGB</value> 5119 <value>GRBG</value> 5120 <value>GBRG</value> 5121 <value>BGGR</value> 5122 <value>RGB 5123 <notes>Sensor is not Bayer; output has 3 16-bit 5124 values for each pixel, instead of just 1 16-bit value 5125 per pixel.</notes></value> 5126 </enum> 5127 <description>The arrangement of color filters on sensor; 5128 represents the colors in the top-left 2x2 section of 5129 the sensor, in reading order.</description> 5130 <tag id="RAW" /> 5131 </entry> 5132 <entry name="exposureTimeRange" type="int64" visibility="public" 5133 type_notes="nanoseconds" container="array" typedef="rangeLong" 5134 hwlevel="full"> 5135 <array> 5136 <size>2</size> 5137 </array> 5138 <description>The range of image exposure times for android.sensor.exposureTime supported 5139 by this camera device. 5140 </description> 5141 <units>Nanoseconds</units> 5142 <range>The minimum exposure time will be less than 100 us. For FULL 5143 capability devices (android.info.supportedHardwareLevel == FULL), 5144 the maximum exposure time will be greater than 100ms.</range> 5145 <hal_details>For FULL capability devices (android.info.supportedHardwareLevel == FULL), 5146 The maximum of the range SHOULD be at least 1 second (1e9), MUST be at least 5147 100ms. 5148 </hal_details> 5149 <tag id="V1" /> 5150 </entry> 5151 <entry name="maxFrameDuration" type="int64" visibility="public" 5152 hwlevel="full"> 5153 <description>The maximum possible frame duration (minimum frame rate) for 5154 android.sensor.frameDuration that is supported this camera device.</description> 5155 <units>Nanoseconds</units> 5156 <range>For FULL capability devices 5157 (android.info.supportedHardwareLevel == FULL), at least 100ms. 5158 </range> 5159 <details>Attempting to use frame durations beyond the maximum will result in the frame 5160 duration being clipped to the maximum. See that control for a full definition of frame 5161 durations. 5162 5163 Refer to StreamConfigurationMap#getOutputMinFrameDuration(int,Size) for the minimum 5164 frame duration values. 5165 </details> 5166 <hal_details> 5167 For FULL capability devices (android.info.supportedHardwareLevel == FULL), 5168 The maximum of the range SHOULD be at least 5169 1 second (1e9), MUST be at least 100ms (100e6). 5170 5171 android.sensor.info.maxFrameDuration must be greater or 5172 equal to the android.sensor.info.exposureTimeRange max 5173 value (since exposure time overrides frame duration). 5174 5175 Available minimum frame durations for JPEG must be no greater 5176 than that of the YUV_420_888/IMPLEMENTATION_DEFINED 5177 minimum frame durations (for that respective size). 5178 5179 Since JPEG processing is considered offline and can take longer than 5180 a single uncompressed capture, refer to 5181 android.scaler.availableStallDurations 5182 for details about encoding this scenario. 5183 </hal_details> 5184 <tag id="V1" /> 5185 </entry> 5186 <entry name="physicalSize" type="float" visibility="public" 5187 type_notes="width x height" 5188 container="array" typedef="sizeF" hwlevel="legacy"> 5189 <array> 5190 <size>2</size> 5191 </array> 5192 <description>The physical dimensions of the full pixel 5193 array.</description> 5194 <units>Millimeters</units> 5195 <details>This is the physical size of the sensor pixel 5196 array defined by android.sensor.info.pixelArraySize. 5197 </details> 5198 <hal_details>Needed for FOV calculation for old API</hal_details> 5199 <tag id="V1" /> 5200 <tag id="BC" /> 5201 </entry> 5202 <entry name="pixelArraySize" type="int32" visibility="public" 5203 container="array" typedef="size" hwlevel="legacy"> 5204 <array> 5205 <size>2</size> 5206 </array> 5207 <description>Dimensions of the full pixel array, possibly 5208 including black calibration pixels.</description> 5209 <units>Pixels</units> 5210 <details>The pixel count of the full pixel array, 5211 which covers android.sensor.info.physicalSize area. 5212 5213 If a camera device supports raw sensor formats, either this 5214 or android.sensor.info.activeArraySize is the maximum output 5215 raw size listed in android.scaler.streamConfigurationMap. 5216 If a size corresponding to pixelArraySize is listed, the resulting 5217 raw sensor image will include black pixels. 5218 5219 Some parts of the full pixel array may not receive light from the scene, 5220 or are otherwise inactive. The android.sensor.info.activeArraySize key 5221 defines the rectangle of active pixels that actually forms an image. 5222 </details> 5223 <tag id="RAW" /> 5224 <tag id="BC" /> 5225 </entry> 5226 <entry name="whiteLevel" type="int32" visibility="public"> 5227 <description> 5228 Maximum raw value output by sensor. 5229 </description> 5230 <range>&gt; 255 (8-bit output)</range> 5231 <details> 5232 This specifies the fully-saturated encoding level for the raw 5233 sample values from the sensor. This is typically caused by the 5234 sensor becoming highly non-linear or clipping. The minimum for 5235 each channel is specified by the offset in the 5236 android.sensor.blackLevelPattern key. 5237 5238 The white level is typically determined either by sensor bit depth 5239 (8-14 bits is expected), or by the point where the sensor response 5240 becomes too non-linear to be useful. The default value for this is 5241 maximum representable value for a 16-bit raw sample (2^16 - 1). 5242 </details> 5243 <hal_details> 5244 The full bit depth of the sensor must be available in the raw data, 5245 so the value for linear sensors should not be significantly lower 5246 than maximum raw value supported, i.e. 2^(sensor bits per pixel). 5247 </hal_details> 5248 <tag id="RAW" /> 5249 </entry> 5250 <entry name="timestampSource" type="byte" visibility="public" 5251 enum="true" hwlevel="legacy"> 5252 <enum> 5253 <value>UNKNOWN 5254 <notes> 5255 Timestamps from android.sensor.timestamp are in nanoseconds and monotonic, 5256 but can not be compared to timestamps from other subsystems 5257 (e.g. accelerometer, gyro etc.), or other instances of the same or different 5258 camera devices in the same system. Timestamps between streams and results for 5259 a single camera instance are comparable, and the timestamps for all buffers 5260 and the result metadata generated by a single capture are identical. 5261 </notes> 5262 </value> 5263 <value>REALTIME 5264 <notes> 5265 Timestamps from android.sensor.timestamp are in the same timebase as 5266 android.os.SystemClock#elapsedRealtimeNanos(), 5267 and they can be compared to other timestamps using that base. 5268 </notes> 5269 </value> 5270 </enum> 5271 <description>The time base source for sensor capture start timestamps.</description> 5272 <details> 5273 The timestamps provided for captures are always in nanoseconds and monotonic, but 5274 may not based on a time source that can be compared to other system time sources. 5275 5276 This characteristic defines the source for the timestamps, and therefore whether they 5277 can be compared against other system time sources/timestamps. 5278 </details> 5279 <tag id="V1" /> 5280 </entry> 5281 </namespace> 5282 <entry name="referenceIlluminant1" type="byte" visibility="public" 5283 enum="true"> 5284 <enum> 5285 <value id="1">DAYLIGHT</value> 5286 <value id="2">FLUORESCENT</value> 5287 <value id="3">TUNGSTEN 5288 <notes>Incandescent light</notes> 5289 </value> 5290 <value id="4">FLASH</value> 5291 <value id="9">FINE_WEATHER</value> 5292 <value id="10">CLOUDY_WEATHER</value> 5293 <value id="11">SHADE</value> 5294 <value id="12">DAYLIGHT_FLUORESCENT 5295 <notes>D 5700 - 7100K</notes> 5296 </value> 5297 <value id="13">DAY_WHITE_FLUORESCENT 5298 <notes>N 4600 - 5400K</notes> 5299 </value> 5300 <value id="14">COOL_WHITE_FLUORESCENT 5301 <notes>W 3900 - 4500K</notes> 5302 </value> 5303 <value id="15">WHITE_FLUORESCENT 5304 <notes>WW 3200 - 3700K</notes> 5305 </value> 5306 <value id="17">STANDARD_A</value> 5307 <value id="18">STANDARD_B</value> 5308 <value id="19">STANDARD_C</value> 5309 <value id="20">D55</value> 5310 <value id="21">D65</value> 5311 <value id="22">D75</value> 5312 <value id="23">D50</value> 5313 <value id="24">ISO_STUDIO_TUNGSTEN</value> 5314 </enum> 5315 <description> 5316 The standard reference illuminant used as the scene light source when 5317 calculating the android.sensor.colorTransform1, 5318 android.sensor.calibrationTransform1, and 5319 android.sensor.forwardMatrix1 matrices. 5320 </description> 5321 <details> 5322 The values in this key correspond to the values defined for the 5323 EXIF LightSource tag. These illuminants are standard light sources 5324 that are often used calibrating camera devices. 5325 5326 If this key is present, then android.sensor.colorTransform1, 5327 android.sensor.calibrationTransform1, and 5328 android.sensor.forwardMatrix1 will also be present. 5329 5330 Some devices may choose to provide a second set of calibration 5331 information for improved quality, including 5332 android.sensor.referenceIlluminant2 and its corresponding matrices. 5333 </details> 5334 <hal_details> 5335 The first reference illuminant (android.sensor.referenceIlluminant1) 5336 and corresponding matrices must be present to support the RAW capability 5337 and DNG output. 5338 5339 When producing raw images with a color profile that has only been 5340 calibrated against a single light source, it is valid to omit 5341 android.sensor.referenceIlluminant2 along with the 5342 android.sensor.colorTransform2, android.sensor.calibrationTransform2, 5343 and android.sensor.forwardMatrix2 matrices. 5344 5345 If only android.sensor.referenceIlluminant1 is included, it should be 5346 chosen so that it is representative of typical scene lighting. In 5347 general, D50 or DAYLIGHT will be chosen for this case. 5348 5349 If both android.sensor.referenceIlluminant1 and 5350 android.sensor.referenceIlluminant2 are included, they should be 5351 chosen to represent the typical range of scene lighting conditions. 5352 In general, low color temperature illuminant such as Standard-A will 5353 be chosen for the first reference illuminant and a higher color 5354 temperature illuminant such as D65 will be chosen for the second 5355 reference illuminant. 5356 </hal_details> 5357 <tag id="RAW" /> 5358 </entry> 5359 <entry name="referenceIlluminant2" type="byte" visibility="public"> 5360 <description> 5361 The standard reference illuminant used as the scene light source when 5362 calculating the android.sensor.colorTransform2, 5363 android.sensor.calibrationTransform2, and 5364 android.sensor.forwardMatrix2 matrices. 5365 </description> 5366 <range>Any value listed in android.sensor.referenceIlluminant1</range> 5367 <details> 5368 See android.sensor.referenceIlluminant1 for more details. 5369 5370 If this key is present, then android.sensor.colorTransform2, 5371 android.sensor.calibrationTransform2, and 5372 android.sensor.forwardMatrix2 will also be present. 5373 </details> 5374 <tag id="RAW" /> 5375 </entry> 5376 <entry name="calibrationTransform1" type="rational" 5377 visibility="public" optional="true" 5378 type_notes="3x3 matrix in row-major-order" container="array" 5379 typedef="colorSpaceTransform"> 5380 <array> 5381 <size>3</size> 5382 <size>3</size> 5383 </array> 5384 <description> 5385 A per-device calibration transform matrix that maps from the 5386 reference sensor colorspace to the actual device sensor colorspace. 5387 </description> 5388 <details> 5389 This matrix is used to correct for per-device variations in the 5390 sensor colorspace, and is used for processing raw buffer data. 5391 5392 The matrix is expressed as a 3x3 matrix in row-major-order, and 5393 contains a per-device calibration transform that maps colors 5394 from reference sensor color space (i.e. the "golden module" 5395 colorspace) into this camera device's native sensor color 5396 space under the first reference illuminant 5397 (android.sensor.referenceIlluminant1). 5398 </details> 5399 <tag id="RAW" /> 5400 </entry> 5401 <entry name="calibrationTransform2" type="rational" 5402 visibility="public" optional="true" 5403 type_notes="3x3 matrix in row-major-order" container="array" 5404 typedef="colorSpaceTransform"> 5405 <array> 5406 <size>3</size> 5407 <size>3</size> 5408 </array> 5409 <description> 5410 A per-device calibration transform matrix that maps from the 5411 reference sensor colorspace to the actual device sensor colorspace 5412 (this is the colorspace of the raw buffer data). 5413 </description> 5414 <details> 5415 This matrix is used to correct for per-device variations in the 5416 sensor colorspace, and is used for processing raw buffer data. 5417 5418 The matrix is expressed as a 3x3 matrix in row-major-order, and 5419 contains a per-device calibration transform that maps colors 5420 from reference sensor color space (i.e. the "golden module" 5421 colorspace) into this camera device's native sensor color 5422 space under the second reference illuminant 5423 (android.sensor.referenceIlluminant2). 5424 5425 This matrix will only be present if the second reference 5426 illuminant is present. 5427 </details> 5428 <tag id="RAW" /> 5429 </entry> 5430 <entry name="colorTransform1" type="rational" 5431 visibility="public" optional="true" 5432 type_notes="3x3 matrix in row-major-order" container="array" 5433 typedef="colorSpaceTransform"> 5434 <array> 5435 <size>3</size> 5436 <size>3</size> 5437 </array> 5438 <description> 5439 A matrix that transforms color values from CIE XYZ color space to 5440 reference sensor color space. 5441 </description> 5442 <details> 5443 This matrix is used to convert from the standard CIE XYZ color 5444 space to the reference sensor colorspace, and is used when processing 5445 raw buffer data. 5446 5447 The matrix is expressed as a 3x3 matrix in row-major-order, and 5448 contains a color transform matrix that maps colors from the CIE 5449 XYZ color space to the reference sensor color space (i.e. the 5450 "golden module" colorspace) under the first reference illuminant 5451 (android.sensor.referenceIlluminant1). 5452 5453 The white points chosen in both the reference sensor color space 5454 and the CIE XYZ colorspace when calculating this transform will 5455 match the standard white point for the first reference illuminant 5456 (i.e. no chromatic adaptation will be applied by this transform). 5457 </details> 5458 <tag id="RAW" /> 5459 </entry> 5460 <entry name="colorTransform2" type="rational" 5461 visibility="public" optional="true" 5462 type_notes="3x3 matrix in row-major-order" container="array" 5463 typedef="colorSpaceTransform"> 5464 <array> 5465 <size>3</size> 5466 <size>3</size> 5467 </array> 5468 <description> 5469 A matrix that transforms color values from CIE XYZ color space to 5470 reference sensor color space. 5471 </description> 5472 <details> 5473 This matrix is used to convert from the standard CIE XYZ color 5474 space to the reference sensor colorspace, and is used when processing 5475 raw buffer data. 5476 5477 The matrix is expressed as a 3x3 matrix in row-major-order, and 5478 contains a color transform matrix that maps colors from the CIE 5479 XYZ color space to the reference sensor color space (i.e. the 5480 "golden module" colorspace) under the second reference illuminant 5481 (android.sensor.referenceIlluminant2). 5482 5483 The white points chosen in both the reference sensor color space 5484 and the CIE XYZ colorspace when calculating this transform will 5485 match the standard white point for the second reference illuminant 5486 (i.e. no chromatic adaptation will be applied by this transform). 5487 5488 This matrix will only be present if the second reference 5489 illuminant is present. 5490 </details> 5491 <tag id="RAW" /> 5492 </entry> 5493 <entry name="forwardMatrix1" type="rational" 5494 visibility="public" optional="true" 5495 type_notes="3x3 matrix in row-major-order" container="array" 5496 typedef="colorSpaceTransform"> 5497 <array> 5498 <size>3</size> 5499 <size>3</size> 5500 </array> 5501 <description> 5502 A matrix that transforms white balanced camera colors from the reference 5503 sensor colorspace to the CIE XYZ colorspace with a D50 whitepoint. 5504 </description> 5505 <details> 5506 This matrix is used to convert to the standard CIE XYZ colorspace, and 5507 is used when processing raw buffer data. 5508 5509 This matrix is expressed as a 3x3 matrix in row-major-order, and contains 5510 a color transform matrix that maps white balanced colors from the 5511 reference sensor color space to the CIE XYZ color space with a D50 white 5512 point. 5513 5514 Under the first reference illuminant (android.sensor.referenceIlluminant1) 5515 this matrix is chosen so that the standard white point for this reference 5516 illuminant in the reference sensor colorspace is mapped to D50 in the 5517 CIE XYZ colorspace. 5518 </details> 5519 <tag id="RAW" /> 5520 </entry> 5521 <entry name="forwardMatrix2" type="rational" 5522 visibility="public" optional="true" 5523 type_notes="3x3 matrix in row-major-order" container="array" 5524 typedef="colorSpaceTransform"> 5525 <array> 5526 <size>3</size> 5527 <size>3</size> 5528 </array> 5529 <description> 5530 A matrix that transforms white balanced camera colors from the reference 5531 sensor colorspace to the CIE XYZ colorspace with a D50 whitepoint. 5532 </description> 5533 <details> 5534 This matrix is used to convert to the standard CIE XYZ colorspace, and 5535 is used when processing raw buffer data. 5536 5537 This matrix is expressed as a 3x3 matrix in row-major-order, and contains 5538 a color transform matrix that maps white balanced colors from the 5539 reference sensor color space to the CIE XYZ color space with a D50 white 5540 point. 5541 5542 Under the second reference illuminant (android.sensor.referenceIlluminant2) 5543 this matrix is chosen so that the standard white point for this reference 5544 illuminant in the reference sensor colorspace is mapped to D50 in the 5545 CIE XYZ colorspace. 5546 5547 This matrix will only be present if the second reference 5548 illuminant is present. 5549 </details> 5550 <tag id="RAW" /> 5551 </entry> 5552 <entry name="baseGainFactor" type="rational" 5553 optional="true"> 5554 <description>Gain factor from electrons to raw units when 5555 ISO=100</description> 5556 <tag id="FUTURE" /> 5557 </entry> 5558 <entry name="blackLevelPattern" type="int32" visibility="public" 5559 optional="true" type_notes="2x2 raw count block" container="array" 5560 typedef="blackLevelPattern"> 5561 <array> 5562 <size>4</size> 5563 </array> 5564 <description> 5565 A fixed black level offset for each of the color filter arrangement 5566 (CFA) mosaic channels. 5567 </description> 5568 <range>&gt;= 0 for each.</range> 5569 <details> 5570 This key specifies the zero light value for each of the CFA mosaic 5571 channels in the camera sensor. The maximal value output by the 5572 sensor is represented by the value in android.sensor.info.whiteLevel. 5573 5574 The values are given in the same order as channels listed for the CFA 5575 layout key (see android.sensor.info.colorFilterArrangement), i.e. the 5576 nth value given corresponds to the black level offset for the nth 5577 color channel listed in the CFA. 5578 </details> 5579 <hal_details> 5580 The values are given in row-column scan order, with the first value 5581 corresponding to the element of the CFA in row=0, column=0. 5582 </hal_details> 5583 <tag id="RAW" /> 5584 </entry> 5585 <entry name="maxAnalogSensitivity" type="int32" visibility="public" 5586 optional="true" hwlevel="full"> 5587 <description>Maximum sensitivity that is implemented 5588 purely through analog gain.</description> 5589 <details>For android.sensor.sensitivity values less than or 5590 equal to this, all applied gain must be analog. For 5591 values above this, the gain applied can be a mix of analog and 5592 digital.</details> 5593 <tag id="V1" /> 5594 <tag id="FULL" /> 5595 </entry> 5596 <entry name="orientation" type="int32" visibility="public" 5597 hwlevel="legacy"> 5598 <description>Clockwise angle through which the output image needs to be rotated to be 5599 upright on the device screen in its native orientation. 5600 </description> 5601 <units>Degrees of clockwise rotation; always a multiple of 5602 90</units> 5603 <range>0, 90, 180, 270</range> 5604 <details> 5605 Also defines the direction of rolling shutter readout, which is from top to bottom in 5606 the sensor's coordinate system. 5607 </details> 5608 <tag id="BC" /> 5609 </entry> 5610 <entry name="profileHueSatMapDimensions" type="int32" 5611 visibility="system" optional="true" 5612 type_notes="Number of samples for hue, saturation, and value" 5613 container="array"> 5614 <array> 5615 <size>3</size> 5616 </array> 5617 <description> 5618 The number of input samples for each dimension of 5619 android.sensor.profileHueSatMap. 5620 </description> 5621 <range> 5622 Hue &gt;= 1, 5623 Saturation &gt;= 2, 5624 Value &gt;= 1 5625 </range> 5626 <details> 5627 The number of input samples for the hue, saturation, and value 5628 dimension of android.sensor.profileHueSatMap. The order of the 5629 dimensions given is hue, saturation, value; where hue is the 0th 5630 element. 5631 </details> 5632 <tag id="RAW" /> 5633 </entry> 5634 </static> 5635 <dynamic> 5636 <clone entry="android.sensor.exposureTime" kind="controls"> 5637 </clone> 5638 <clone entry="android.sensor.frameDuration" 5639 kind="controls"></clone> 5640 <clone entry="android.sensor.sensitivity" kind="controls"> 5641 </clone> 5642 <entry name="timestamp" type="int64" visibility="public" 5643 hwlevel="legacy"> 5644 <description>Time at start of exposure of first 5645 row of the image sensor active array, in nanoseconds.</description> 5646 <units>Nanoseconds</units> 5647 <range>&gt; 0</range> 5648 <details>The timestamps are also included in all image 5649 buffers produced for the same capture, and will be identical 5650 on all the outputs. 5651 5652 When android.sensor.info.timestampSource `==` UNKNOWN, 5653 the timestamps measure time since an unspecified starting point, 5654 and are monotonically increasing. They can be compared with the 5655 timestamps for other captures from the same camera device, but are 5656 not guaranteed to be comparable to any other time source. 5657 5658 When android.sensor.info.timestampSource `==` REALTIME, 5659 the timestamps measure time in the same timebase as 5660 android.os.SystemClock#elapsedRealtimeNanos(), and they can be 5661 compared to other timestamps from other subsystems that are using 5662 that base. 5663 </details> 5664 <hal_details> 5665 All timestamps must be in reference to the kernel's 5666 CLOCK_BOOTTIME monotonic clock, which properly accounts for 5667 time spent asleep. This allows for synchronization with 5668 sensors that continue to operate while the system is 5669 otherwise asleep. 5670 5671 If android.sensor.info.timestampSource `==` REALTIME, 5672 The timestamp must be synchronized with the timestamps from other 5673 sensor subsystems that are using the same timebase. 5674 </hal_details> 5675 <tag id="BC" /> 5676 </entry> 5677 <entry name="temperature" type="float" 5678 optional="true"> 5679 <description>The temperature of the sensor, sampled at the time 5680 exposure began for this frame. 5681 5682 The thermal diode being queried should be inside the sensor PCB, or 5683 somewhere close to it. 5684 </description> 5685 5686 <units>Celsius</units> 5687 <range>Optional. This value is missing if no temperature is available.</range> 5688 <tag id="FUTURE" /> 5689 </entry> 5690 <entry name="neutralColorPoint" type="rational" visibility="public" 5691 optional="true" container="array"> 5692 <array> 5693 <size>3</size> 5694 </array> 5695 <description> 5696 The estimated camera neutral color in the native sensor colorspace at 5697 the time of capture. 5698 </description> 5699 <details> 5700 This value gives the neutral color point encoded as an RGB value in the 5701 native sensor color space. The neutral color point indicates the 5702 currently estimated white point of the scene illumination. It can be 5703 used to interpolate between the provided color transforms when 5704 processing raw sensor data. 5705 5706 The order of the values is R, G, B; where R is in the lowest index. 5707 </details> 5708 <tag id="RAW" /> 5709 </entry> 5710 <entry name="noiseProfile" type="double" visibility="public" 5711 optional="true" type_notes="Pairs of noise model coefficients" 5712 container="array" typedef="pairDoubleDouble"> 5713 <array> 5714 <size>2</size> 5715 <size>CFA Channels</size> 5716 </array> 5717 <description> 5718 Noise model coefficients for each CFA mosaic channel. 5719 </description> 5720 <details> 5721 This key contains two noise model coefficients for each CFA channel 5722 corresponding to the sensor amplification (S) and sensor readout 5723 noise (O). These are given as pairs of coefficients for each channel 5724 in the same order as channels listed for the CFA layout key 5725 (see android.sensor.info.colorFilterArrangement). This is 5726 represented as an array of Pair&lt;Double, Double&gt;, where 5727 the first member of the Pair at index n is the S coefficient and the 5728 second member is the O coefficient for the nth color channel in the CFA. 5729 5730 These coefficients are used in a two parameter noise model to describe 5731 the amount of noise present in the image for each CFA channel. The 5732 noise model used here is: 5733 5734 N(x) = sqrt(Sx + O) 5735 5736 Where x represents the recorded signal of a CFA channel normalized to 5737 the range [0, 1], and S and O are the noise model coeffiecients for 5738 that channel. 5739 5740 A more detailed description of the noise model can be found in the 5741 Adobe DNG specification for the NoiseProfile tag. 5742 </details> 5743 <hal_details> 5744 For a CFA layout of RGGB, the list of coefficients would be given as 5745 an array of doubles S0,O0,S1,O1,..., where S0 and O0 are the coefficients 5746 for the red channel, S1 and O1 are the coefficients for the first green 5747 channel, etc. 5748 </hal_details> 5749 <tag id="RAW" /> 5750 </entry> 5751 <entry name="profileHueSatMap" type="float" 5752 visibility="system" optional="true" 5753 type_notes="Mapping for hue, saturation, and value" 5754 container="array"> 5755 <array> 5756 <size>hue_samples</size> 5757 <size>saturation_samples</size> 5758 <size>value_samples</size> 5759 <size>3</size> 5760 </array> 5761 <description> 5762 A mapping containing a hue shift, saturation scale, and value scale 5763 for each pixel. 5764 </description> 5765 <units> 5766 The hue shift is given in degrees; saturation and value scale factors are 5767 unitless and are between 0 and 1 inclusive 5768 </units> 5769 <details> 5770 hue_samples, saturation_samples, and value_samples are given in 5771 android.sensor.profileHueSatMapDimensions. 5772 5773 Each entry of this map contains three floats corresponding to the 5774 hue shift, saturation scale, and value scale, respectively; where the 5775 hue shift has the lowest index. The map entries are stored in the key 5776 in nested loop order, with the value divisions in the outer loop, the 5777 hue divisions in the middle loop, and the saturation divisions in the 5778 inner loop. All zero input saturation entries are required to have a 5779 value scale factor of 1.0. 5780 </details> 5781 <tag id="RAW" /> 5782 </entry> 5783 <entry name="profileToneCurve" type="float" 5784 visibility="system" optional="true" 5785 type_notes="Samples defining a spline for a tone-mapping curve" 5786 container="array"> 5787 <array> 5788 <size>samples</size> 5789 <size>2</size> 5790 </array> 5791 <description> 5792 A list of x,y samples defining a tone-mapping curve for gamma adjustment. 5793 </description> 5794 <range> 5795 Each sample has an input range of `[0, 1]` and an output range of 5796 `[0, 1]`. The first sample is required to be `(0, 0)`, and the last 5797 sample is required to be `(1, 1)`. 5798 </range> 5799 <details> 5800 This key contains a default tone curve that can be applied while 5801 processing the image as a starting point for user adjustments. 5802 The curve is specified as a list of value pairs in linear gamma. 5803 The curve is interpolated using a cubic spline. 5804 </details> 5805 <tag id="RAW" /> 5806 </entry> 5807 <entry name="greenSplit" type="float" visibility="public" optional="true"> 5808 <description> 5809 The worst-case divergence between Bayer green channels. 5810 </description> 5811 <range> 5812 &gt;= 0 5813 </range> 5814 <details> 5815 This value is an estimate of the worst case split between the 5816 Bayer green channels in the red and blue rows in the sensor color 5817 filter array. 5818 5819 The green split is calculated as follows: 5820 5821 1. A 5x5 pixel (or larger) window W within the active sensor array is 5822 chosen. The term 'pixel' here is taken to mean a group of 4 Bayer 5823 mosaic channels (R, Gr, Gb, B). The location and size of the window 5824 chosen is implementation defined, and should be chosen to provide a 5825 green split estimate that is both representative of the entire image 5826 for this camera sensor, and can be calculated quickly. 5827 1. The arithmetic mean of the green channels from the red 5828 rows (mean_Gr) within W is computed. 5829 1. The arithmetic mean of the green channels from the blue 5830 rows (mean_Gb) within W is computed. 5831 1. The maximum ratio R of the two means is computed as follows: 5832 `R = max((mean_Gr + 1)/(mean_Gb + 1), (mean_Gb + 1)/(mean_Gr + 1))` 5833 5834 The ratio R is the green split divergence reported for this property, 5835 which represents how much the green channels differ in the mosaic 5836 pattern. This value is typically used to determine the treatment of 5837 the green mosaic channels when demosaicing. 5838 5839 The green split value can be roughly interpreted as follows: 5840 5841 * R &lt; 1.03 is a negligible split (&lt;3% divergence). 5842 * 1.20 &lt;= R &gt;= 1.03 will require some software 5843 correction to avoid demosaic errors (3-20% divergence). 5844 * R &gt; 1.20 will require strong software correction to produce 5845 a usuable image (&gt;20% divergence). 5846 </details> 5847 <hal_details> 5848 The green split given may be a static value based on prior 5849 characterization of the camera sensor using the green split 5850 calculation method given here over a large, representative, sample 5851 set of images. Other methods of calculation that produce equivalent 5852 results, and can be interpreted in the same manner, may be used. 5853 </hal_details> 5854 <tag id="RAW" /> 5855 </entry> 5856 </dynamic> 5857 <controls> 5858 <entry name="testPatternData" type="int32" visibility="public" optional="true" container="array"> 5859 <array> 5860 <size>4</size> 5861 </array> 5862 <description> 5863 A pixel `[R, G_even, G_odd, B]` that supplies the test pattern 5864 when android.sensor.testPatternMode is SOLID_COLOR. 5865 </description> 5866 <details> 5867 Each color channel is treated as an unsigned 32-bit integer. 5868 The camera device then uses the most significant X bits 5869 that correspond to how many bits are in its Bayer raw sensor 5870 output. 5871 5872 For example, a sensor with RAW10 Bayer output would use the 5873 10 most significant bits from each color channel. 5874 </details> 5875 <hal_details> 5876 </hal_details> 5877 </entry> 5878 <entry name="testPatternMode" type="int32" visibility="public" optional="true" 5879 enum="true"> 5880 <enum> 5881 <value>OFF 5882 <notes>No test pattern mode is used, and the camera 5883 device returns captures from the image sensor. 5884 5885 This is the default if the key is not set.</notes> 5886 </value> 5887 <value>SOLID_COLOR 5888 <notes> 5889 Each pixel in `[R, G_even, G_odd, B]` is replaced by its 5890 respective color channel provided in 5891 android.sensor.testPatternData. 5892 5893 For example: 5894 5895 android.testPatternData = [0, 0xFFFFFFFF, 0xFFFFFFFF, 0] 5896 5897 All green pixels are 100% green. All red/blue pixels are black. 5898 5899 android.testPatternData = [0xFFFFFFFF, 0, 0xFFFFFFFF, 0] 5900 5901 All red pixels are 100% red. Only the odd green pixels 5902 are 100% green. All blue pixels are 100% black. 5903 </notes> 5904 </value> 5905 <value>COLOR_BARS 5906 <notes> 5907 All pixel data is replaced with an 8-bar color pattern. 5908 5909 The vertical bars (left-to-right) are as follows: 5910 5911 * 100% white 5912 * yellow 5913 * cyan 5914 * green 5915 * magenta 5916 * red 5917 * blue 5918 * black 5919 5920 In general the image would look like the following: 5921 5922 W Y C G M R B K 5923 W Y C G M R B K 5924 W Y C G M R B K 5925 W Y C G M R B K 5926 W Y C G M R B K 5927 . . . . . . . . 5928 . . . . . . . . 5929 . . . . . . . . 5930 5931 (B = Blue, K = Black) 5932 5933 Each bar should take up 1/8 of the sensor pixel array width. 5934 When this is not possible, the bar size should be rounded 5935 down to the nearest integer and the pattern can repeat 5936 on the right side. 5937 5938 Each bar's height must always take up the full sensor 5939 pixel array height. 5940 5941 Each pixel in this test pattern must be set to either 5942 0% intensity or 100% intensity. 5943 </notes> 5944 </value> 5945 <value>COLOR_BARS_FADE_TO_GRAY 5946 <notes> 5947 The test pattern is similar to COLOR_BARS, except that 5948 each bar should start at its specified color at the top, 5949 and fade to gray at the bottom. 5950 5951 Furthermore each bar is further subdivided into a left and 5952 right half. The left half should have a smooth gradient, 5953 and the right half should have a quantized gradient. 5954 5955 In particular, the right half's should consist of blocks of the 5956 same color for 1/16th active sensor pixel array width. 5957 5958 The least significant bits in the quantized gradient should 5959 be copied from the most significant bits of the smooth gradient. 5960 5961 The height of each bar should always be a multiple of 128. 5962 When this is not the case, the pattern should repeat at the bottom 5963 of the image. 5964 </notes> 5965 </value> 5966 <value>PN9 5967 <notes> 5968 All pixel data is replaced by a pseudo-random sequence 5969 generated from a PN9 512-bit sequence (typically implemented 5970 in hardware with a linear feedback shift register). 5971 5972 The generator should be reset at the beginning of each frame, 5973 and thus each subsequent raw frame with this test pattern should 5974 be exactly the same as the last. 5975 </notes> 5976 </value> 5977 <value id="256">CUSTOM1 5978 <notes>The first custom test pattern. All custom patterns that are 5979 available only on this camera device are at least this numeric 5980 value. 5981 5982 All of the custom test patterns will be static 5983 (that is the raw image must not vary from frame to frame). 5984 </notes> 5985 </value> 5986 </enum> 5987 <description>When enabled, the sensor sends a test pattern instead of 5988 doing a real exposure from the camera. 5989 </description> 5990 <range>android.sensor.availableTestPatternModes</range> 5991 <details> 5992 When a test pattern is enabled, all manual sensor controls specified 5993 by android.sensor.* will be ignored. All other controls should 5994 work as normal. 5995 5996 For example, if manual flash is enabled, flash firing should still 5997 occur (and that the test pattern remain unmodified, since the flash 5998 would not actually affect it). 5999 6000 Defaults to OFF. 6001 </details> 6002 <hal_details> 6003 All test patterns are specified in the Bayer domain. 6004 6005 The HAL may choose to substitute test patterns from the sensor 6006 with test patterns from on-device memory. In that case, it should be 6007 indistinguishable to the ISP whether the data came from the 6008 sensor interconnect bus (such as CSI2) or memory. 6009 </hal_details> 6010 </entry> 6011 </controls> 6012 <dynamic> 6013 <clone entry="android.sensor.testPatternData" kind="controls"> 6014 </clone> 6015 <clone entry="android.sensor.testPatternMode" kind="controls"> 6016 </clone> 6017 </dynamic> 6018 <static> 6019 <entry name="availableTestPatternModes" type="int32" visibility="public" optional="true" 6020 type_notes="list of enums" container="array"> 6021 <array> 6022 <size>n</size> 6023 </array> 6024 <description>List of sensor test pattern modes for android.sensor.testPatternMode 6025 supported by this camera device. 6026 </description> 6027 <range>Any value listed in android.sensor.testPatternMode</range> 6028 <details> 6029 Defaults to OFF, and always includes OFF if defined. 6030 </details> 6031 <hal_details> 6032 All custom modes must be >= CUSTOM1. 6033 </hal_details> 6034 </entry> 6035 </static> 6036 <dynamic> 6037 <entry name="rollingShutterSkew" type="int64" visibility="public" hwlevel="limited"> 6038 <description>Duration between the start of first row exposure 6039 and the start of last row exposure.</description> 6040 <units>Nanoseconds</units> 6041 <range> &gt;= 0 and &lt; 6042 StreamConfigurationMap#getOutputMinFrameDuration(int, Size).</range> 6043 <details> 6044 This is the exposure time skew between the first and last 6045 row exposure start times. The first row and the last row are 6046 the first and last rows inside of the 6047 android.sensor.info.activeArraySize. 6048 6049 For typical camera sensors that use rolling shutters, this is also equivalent 6050 to the frame readout time. 6051 </details> 6052 <hal_details> 6053 The HAL must report `0` if the sensor is using global shutter, where all pixels begin 6054 exposure at the same time. 6055 </hal_details> 6056 <tag id="V1" /> 6057 </entry> 6058 </dynamic> 6059 </section> 6060 <section name="shading"> 6061 <controls> 6062 <entry name="mode" type="byte" visibility="public" enum="true" hwlevel="full"> 6063 <enum> 6064 <value>OFF 6065 <notes>No lens shading correction is applied.</notes></value> 6066 <value>FAST 6067 <notes>Apply lens shading corrections, without slowing 6068 frame rate relative to sensor raw output</notes></value> 6069 <value>HIGH_QUALITY 6070 <notes>Apply high-quality lens shading correction, at the 6071 cost of reduced frame rate.</notes></value> 6072 </enum> 6073 <description>Quality of lens shading correction applied 6074 to the image data.</description> 6075 <details> 6076 When set to OFF mode, no lens shading correction will be applied by the 6077 camera device, and an identity lens shading map data will be provided 6078 if `android.statistics.lensShadingMapMode == ON`. For example, for lens 6079 shading map with size of `[ 4, 3 ]`, 6080 the output android.statistics.lensShadingCorrectionMap for this case will be an identity 6081 map shown below: 6082 6083 [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 6084 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 6085 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 6086 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 6087 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 6088 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] 6089 6090 When set to other modes, lens shading correction will be applied by the camera 6091 device. Applications can request lens shading map data by setting 6092 android.statistics.lensShadingMapMode to ON, and then the camera device will provide lens 6093 shading map data in android.statistics.lensShadingCorrectionMap; the returned shading map 6094 data will be the one applied by the camera device for this capture request. 6095 6096 The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore 6097 the reliability of the map data may be affected by the AE and AWB algorithms. When AE and 6098 AWB are in AUTO modes(android.control.aeMode `!=` OFF and android.control.awbMode `!=` 6099 OFF), to get best results, it is recommended that the applications wait for the AE and AWB 6100 to be converged before using the returned shading map data. 6101 </details> 6102 </entry> 6103 <entry name="strength" type="byte"> 6104 <description>Control the amount of shading correction 6105 applied to the images</description> 6106 <units>unitless: 1-10; 10 is full shading 6107 compensation</units> 6108 <tag id="FUTURE" /> 6109 </entry> 6110 </controls> 6111 <dynamic> 6112 <clone entry="android.shading.mode" kind="controls"> 6113 </clone> 6114 </dynamic> 6115 </section> 6116 <section name="statistics"> 6117 <controls> 6118 <entry name="faceDetectMode" type="byte" visibility="public" enum="true" 6119 hwlevel="legacy"> 6120 <enum> 6121 <value>OFF 6122 <notes>Do not include face detection statistics in capture 6123 results.</notes></value> 6124 <value optional="true">SIMPLE 6125 <notes>Return face rectangle and confidence values only. 6126 </notes></value> 6127 <value optional="true">FULL 6128 <notes>Return all face 6129 metadata. 6130 6131 In this mode, face rectangles, scores, landmarks, and face IDs are all valid. 6132 </notes></value> 6133 </enum> 6134 <description>Operating mode for the face detector 6135 unit.</description> 6136 <range>android.statistics.info.availableFaceDetectModes</range> 6137 <details>Whether face detection is enabled, and whether it 6138 should output just the basic fields or the full set of 6139 fields.</details> 6140 <hal_details> 6141 SIMPLE mode must fill in android.statistics.faceRectangles and 6142 android.statistics.faceScores. 6143 FULL mode must also fill in android.statistics.faceIds, and 6144 android.statistics.faceLandmarks. 6145 </hal_details> 6146 <tag id="BC" /> 6147 </entry> 6148 <entry name="histogramMode" type="byte" enum="true" typedef="boolean"> 6149 <enum> 6150 <value>OFF</value> 6151 <value>ON</value> 6152 </enum> 6153 <description>Operating mode for histogram 6154 generation</description> 6155 <tag id="FUTURE" /> 6156 </entry> 6157 <entry name="sharpnessMapMode" type="byte" enum="true" typedef="boolean"> 6158 <enum> 6159 <value>OFF</value> 6160 <value>ON</value> 6161 </enum> 6162 <description>Operating mode for sharpness map 6163 generation</description> 6164 <tag id="FUTURE" /> 6165 </entry> 6166 <entry name="hotPixelMapMode" type="byte" visibility="public" enum="true" 6167 typedef="boolean"> 6168 <enum> 6169 <value>OFF 6170 <notes>Hot pixel map production is disabled. 6171 </notes></value> 6172 <value>ON 6173 <notes>Hot pixel map production is enabled. 6174 </notes></value> 6175 </enum> 6176 <description> 6177 Operating mode for hot pixel map generation. 6178 </description> 6179 <range>android.statistics.info.availableHotPixelMapModes</range> 6180 <details> 6181 If set to `true`, a hot pixel map is returned in android.statistics.hotPixelMap. 6182 If set to `false`, no hot pixel map will be returned. 6183 </details> 6184 <tag id="V1" /> 6185 <tag id="RAW" /> 6186 </entry> 6187 </controls> 6188 <static> 6189 <namespace name="info"> 6190 <entry name="availableFaceDetectModes" type="byte" 6191 visibility="public" 6192 type_notes="List of enums from android.statistics.faceDetectMode" 6193 container="array" 6194 typedef="enumList" 6195 hwlevel="legacy"> 6196 <array> 6197 <size>n</size> 6198 </array> 6199 <description>List of face detection modes for android.statistics.faceDetectMode that are 6200 supported by this camera device. 6201 </description> 6202 <range>Any value listed in android.statistics.faceDetectMode</range> 6203 <details>OFF is always supported. 6204 </details> 6205 </entry> 6206 <entry name="histogramBucketCount" type="int32"> 6207 <description>Number of histogram buckets 6208 supported</description> 6209 <range>&gt;= 64</range> 6210 <tag id="FUTURE" /> 6211 </entry> 6212 <entry name="maxFaceCount" type="int32" visibility="public" hwlevel="legacy"> 6213 <description>The maximum number of simultaneously detectable 6214 faces.</description> 6215 <range>0 for cameras without available face detection; otherwise: 6216 `>=4` for LIMITED or FULL hwlevel devices or 6217 `>0` for LEGACY devices.</range> 6218 <tag id="BC" /> 6219 </entry> 6220 <entry name="maxHistogramCount" type="int32"> 6221 <description>Maximum value possible for a histogram 6222 bucket</description> 6223 <tag id="FUTURE" /> 6224 </entry> 6225 <entry name="maxSharpnessMapValue" type="int32"> 6226 <description>Maximum value possible for a sharpness map 6227 region.</description> 6228 <tag id="FUTURE" /> 6229 </entry> 6230 <entry name="sharpnessMapSize" type="int32" 6231 type_notes="width x height" container="array" typedef="size"> 6232 <array> 6233 <size>2</size> 6234 </array> 6235 <description>Dimensions of the sharpness 6236 map</description> 6237 <range>Must be at least 32 x 32</range> 6238 <tag id="FUTURE" /> 6239 </entry> 6240 <entry name="availableHotPixelMapModes" type="byte" visibility="public" 6241 type_notes="list of enums" container="array" typedef="boolean"> 6242 <array> 6243 <size>n</size> 6244 </array> 6245 <description> 6246 List of hot pixel map output modes for android.statistics.hotPixelMapMode that are 6247 supported by this camera device. 6248 </description> 6249 <range>Any value listed in android.statistics.hotPixelMapMode</range> 6250 <details> 6251 If no hotpixel map output is available for this camera device, this will contain only 6252 `false`. 6253 6254 ON is always supported on devices with the RAW capability. 6255 </details> 6256 <tag id="V1" /> 6257 <tag id="RAW" /> 6258 </entry> 6259 </namespace> 6260 </static> 6261 <dynamic> 6262 <clone entry="android.statistics.faceDetectMode" 6263 kind="controls"></clone> 6264 <entry name="faceIds" type="int32" visibility="hidden" container="array" 6265 hwlevel="legacy"> 6266 <array> 6267 <size>n</size> 6268 </array> 6269 <description>List of unique IDs for detected faces.</description> 6270 <details> 6271 Each detected face is given a unique ID that is valid for as long as the face is visible 6272 to the camera device. A face that leaves the field of view and later returns may be 6273 assigned a new ID. 6274 6275 Only available if android.statistics.faceDetectMode == FULL</details> 6276 <tag id="BC" /> 6277 </entry> 6278 <entry name="faceLandmarks" type="int32" visibility="hidden" 6279 type_notes="(leftEyeX, leftEyeY, rightEyeX, rightEyeY, mouthX, mouthY)" 6280 container="array" hwlevel="legacy"> 6281 <array> 6282 <size>n</size> 6283 <size>6</size> 6284 </array> 6285 <description>List of landmarks for detected 6286 faces.</description> 6287 <details> 6288 The coordinate system is that of android.sensor.info.activeArraySize, with 6289 `(0, 0)` being the top-left pixel of the active array. 6290 6291 Only available if android.statistics.faceDetectMode == FULL</details> 6292 <tag id="BC" /> 6293 </entry> 6294 <entry name="faceRectangles" type="int32" visibility="hidden" 6295 type_notes="(xmin, ymin, xmax, ymax). (0,0) is top-left of active pixel area" 6296 container="array" typedef="rectangle" hwlevel="legacy"> 6297 <array> 6298 <size>n</size> 6299 <size>4</size> 6300 </array> 6301 <description>List of the bounding rectangles for detected 6302 faces.</description> 6303 <details> 6304 The coordinate system is that of android.sensor.info.activeArraySize, with 6305 `(0, 0)` being the top-left pixel of the active array. 6306 6307 Only available if android.statistics.faceDetectMode != OFF</details> 6308 <tag id="BC" /> 6309 </entry> 6310 <entry name="faceScores" type="byte" visibility="hidden" container="array" 6311 hwlevel="legacy"> 6312 <array> 6313 <size>n</size> 6314 </array> 6315 <description>List of the face confidence scores for 6316 detected faces</description> 6317 <range>1-100</range> 6318 <details>Only available if android.statistics.faceDetectMode != OFF. 6319 </details> 6320 <hal_details> 6321 The value should be meaningful (for example, setting 100 at 6322 all times is illegal).</hal_details> 6323 <tag id="BC" /> 6324 </entry> 6325 <entry name="faces" type="int32" visibility="public" synthetic="true" 6326 container="array" typedef="face" hwlevel="legacy"> 6327 <array> 6328 <size>n</size> 6329 </array> 6330 <description>List of the faces detected through camera face detection 6331 in this capture.</description> 6332 <details> 6333 Only available if android.statistics.faceDetectMode `!=` OFF. 6334 </details> 6335 </entry> 6336 <entry name="histogram" type="int32" 6337 type_notes="count of pixels for each color channel that fall into each histogram bucket, scaled to be between 0 and maxHistogramCount" 6338 container="array"> 6339 <array> 6340 <size>n</size> 6341 <size>3</size> 6342 </array> 6343 <description>A 3-channel histogram based on the raw 6344 sensor data</description> 6345 <details>The k'th bucket (0-based) covers the input range 6346 (with w = android.sensor.info.whiteLevel) of [ k * w/N, 6347 (k + 1) * w / N ). If only a monochrome sharpness map is 6348 supported, all channels should have the same data</details> 6349 <tag id="FUTURE" /> 6350 </entry> 6351 <clone entry="android.statistics.histogramMode" 6352 kind="controls"></clone> 6353 <entry name="sharpnessMap" type="int32" 6354 type_notes="estimated sharpness for each region of the input image. Normalized to be between 0 and maxSharpnessMapValue. Higher values mean sharper (better focused)" 6355 container="array"> 6356 <array> 6357 <size>n</size> 6358 <size>m</size> 6359 <size>3</size> 6360 </array> 6361 <description>A 3-channel sharpness map, based on the raw 6362 sensor data</description> 6363 <details>If only a monochrome sharpness map is supported, 6364 all channels should have the same data</details> 6365 <tag id="FUTURE" /> 6366 </entry> 6367 <clone entry="android.statistics.sharpnessMapMode" 6368 kind="controls"></clone> 6369 <entry name="lensShadingCorrectionMap" type="byte" visibility="public" 6370 typedef="lensShadingMap" hwlevel="full"> 6371 <description>The shading map is a low-resolution floating-point map 6372 that lists the coefficients used to correct for vignetting, for each 6373 Bayer color channel.</description> 6374 <range>Each gain factor is &gt;= 1</range> 6375 <details>The least shaded section of the image should have a gain factor 6376 of 1; all other sections should have gains above 1. 6377 6378 When android.colorCorrection.mode = TRANSFORM_MATRIX, the map 6379 must take into account the colorCorrection settings. 6380 6381 The shading map is for the entire active pixel array, and is not 6382 affected by the crop region specified in the request. Each shading map 6383 entry is the value of the shading compensation map over a specific 6384 pixel on the sensor. Specifically, with a (N x M) resolution shading 6385 map, and an active pixel array size (W x H), shading map entry 6386 (x,y) (0 ... N-1, 0 ... M-1) is the value of the shading map at 6387 pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels. 6388 The map is assumed to be bilinearly interpolated between the sample points. 6389 6390 The channel order is [R, Geven, Godd, B], where Geven is the green 6391 channel for the even rows of a Bayer pattern, and Godd is the odd rows. 6392 The shading map is stored in a fully interleaved format. 6393 6394 The shading map should have on the order of 30-40 rows and columns, 6395 and must be smaller than 64x64. 6396 6397 As an example, given a very small map defined as: 6398 6399 width,height = [ 4, 3 ] 6400 values = 6401 [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2, 6402 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3, 6403 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0, 6404 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2, 6405 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2, 6406 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ] 6407 6408 The low-resolution scaling map images for each channel are 6409 (displayed using nearest-neighbor interpolation): 6410 6411  6412  6413  6414  6415 6416 As a visualization only, inverting the full-color map to recover an 6417 image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives: 6418 6419  6420 </details> 6421 </entry> 6422 <entry name="lensShadingMap" type="float" visibility="hidden" 6423 type_notes="2D array of float gain factors per channel to correct lens shading" 6424 container="array" hwlevel="full"> 6425 <array> 6426 <size>4</size> 6427 <size>n</size> 6428 <size>m</size> 6429 </array> 6430 <description>The shading map is a low-resolution floating-point map 6431 that lists the coefficients used to correct for vignetting, for each 6432 Bayer color channel.</description> 6433 <range>Each gain factor is &gt;= 1</range> 6434 <details>The least shaded section of the image should have a gain factor 6435 of 1; all other sections should have gains above 1. 6436 6437 When android.colorCorrection.mode = TRANSFORM_MATRIX, the map 6438 must take into account the colorCorrection settings. 6439 6440 The shading map is for the entire active pixel array, and is not 6441 affected by the crop region specified in the request. Each shading map 6442 entry is the value of the shading compensation map over a specific 6443 pixel on the sensor. Specifically, with a (N x M) resolution shading 6444 map, and an active pixel array size (W x H), shading map entry 6445 (x,y) (0 ... N-1, 0 ... M-1) is the value of the shading map at 6446 pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels. 6447 The map is assumed to be bilinearly interpolated between the sample points. 6448 6449 The channel order is [R, Geven, Godd, B], where Geven is the green 6450 channel for the even rows of a Bayer pattern, and Godd is the odd rows. 6451 The shading map is stored in a fully interleaved format, and its size 6452 is provided in the camera static metadata by android.lens.info.shadingMapSize. 6453 6454 The shading map should have on the order of 30-40 rows and columns, 6455 and must be smaller than 64x64. 6456 6457 As an example, given a very small map defined as: 6458 6459 android.lens.info.shadingMapSize = [ 4, 3 ] 6460 android.statistics.lensShadingMap = 6461 [ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2, 6462 1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3, 6463 1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0, 6464 1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2, 6465 1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2, 6466 1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ] 6467 6468 The low-resolution scaling map images for each channel are 6469 (displayed using nearest-neighbor interpolation): 6470 6471  6472  6473  6474  6475 6476 As a visualization only, inverting the full-color map to recover an 6477 image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives: 6478 6479  6480 </details> 6481 <hal_details> 6482 The lens shading map calculation may depend on exposure and white balance statistics. 6483 When AE and AWB are in AUTO modes 6484 (android.control.aeMode `!=` OFF and android.control.awbMode `!=` OFF), the HAL 6485 may have all the information it need to generate most accurate lens shading map. When 6486 AE or AWB are in manual mode 6487 (android.control.aeMode `==` OFF or android.control.awbMode `==` OFF), the shading map 6488 may be adversely impacted by manual exposure or white balance parameters. To avoid 6489 generating unreliable shading map data, the HAL may choose to lock the shading map with 6490 the latest known good map generated when the AE and AWB are in AUTO modes. 6491 </hal_details> 6492 </entry> 6493 <entry name="predictedColorGains" type="float" 6494 visibility="hidden" 6495 deprecated="true" 6496 optional="true" 6497 type_notes="A 1D array of floats for 4 color channel gains" 6498 container="array"> 6499 <array> 6500 <size>4</size> 6501 </array> 6502 <description>The best-fit color channel gains calculated 6503 by the camera device's statistics units for the current output frame. 6504 </description> 6505 <details> 6506 This may be different than the gains used for this frame, 6507 since statistics processing on data from a new frame 6508 typically completes after the transform has already been 6509 applied to that frame. 6510 6511 The 4 channel gains are defined in Bayer domain, 6512 see android.colorCorrection.gains for details. 6513 6514 This value should always be calculated by the auto-white balance (AWB) block, 6515 regardless of the android.control.* current values. 6516 </details> 6517 </entry> 6518 <entry name="predictedColorTransform" type="rational" 6519 visibility="hidden" 6520 deprecated="true" 6521 optional="true" 6522 type_notes="3x3 rational matrix in row-major order" 6523 container="array"> 6524 <array> 6525 <size>3</size> 6526 <size>3</size> 6527 </array> 6528 <description>The best-fit color transform matrix estimate 6529 calculated by the camera device's statistics units for the current 6530 output frame.</description> 6531 <details>The camera device will provide the estimate from its 6532 statistics unit on the white balance transforms to use 6533 for the next frame. These are the values the camera device believes 6534 are the best fit for the current output frame. This may 6535 be different than the transform used for this frame, since 6536 statistics processing on data from a new frame typically 6537 completes after the transform has already been applied to 6538 that frame. 6539 6540 These estimates must be provided for all frames, even if 6541 capture settings and color transforms are set by the application. 6542 6543 This value should always be calculated by the auto-white balance (AWB) block, 6544 regardless of the android.control.* current values. 6545 </details> 6546 </entry> 6547 <entry name="sceneFlicker" type="byte" visibility="public" enum="true" 6548 hwlevel="full"> 6549 <enum> 6550 <value>NONE 6551 <notes>The camera device does not detect any flickering illumination 6552 in the current scene.</notes></value> 6553 <value>50HZ 6554 <notes>The camera device detects illumination flickering at 50Hz 6555 in the current scene.</notes></value> 6556 <value>60HZ 6557 <notes>The camera device detects illumination flickering at 60Hz 6558 in the current scene.</notes></value> 6559 </enum> 6560 <description>The camera device estimated scene illumination lighting 6561 frequency.</description> 6562 <details> 6563 Many light sources, such as most fluorescent lights, flicker at a rate 6564 that depends on the local utility power standards. This flicker must be 6565 accounted for by auto-exposure routines to avoid artifacts in captured images. 6566 The camera device uses this entry to tell the application what the scene 6567 illuminant frequency is. 6568 6569 When manual exposure control is enabled 6570 (`android.control.aeMode == OFF` or `android.control.mode == 6571 OFF`), the android.control.aeAntibandingMode doesn't perform 6572 antibanding, and the application can ensure it selects 6573 exposure times that do not cause banding issues by looking 6574 into this metadata field. See 6575 android.control.aeAntibandingMode for more details. 6576 6577 Reports NONE if there doesn't appear to be flickering illumination. 6578 </details> 6579 </entry> 6580 <clone entry="android.statistics.hotPixelMapMode" kind="controls"> 6581 </clone> 6582 <entry name="hotPixelMap" type="int32" visibility="public" 6583 type_notes="list of coordinates based on android.sensor.pixelArraySize" 6584 container="array" typedef="point"> 6585 <array> 6586 <size>2</size> 6587 <size>n</size> 6588 </array> 6589 <description> 6590 List of `(x, y)` coordinates of hot/defective pixels on the sensor. 6591 </description> 6592 <range> 6593 n <= number of pixels on the sensor. 6594 The `(x, y)` coordinates must be bounded by 6595 android.sensor.info.pixelArraySize. 6596 </range> 6597 <details> 6598 A coordinate `(x, y)` must lie between `(0, 0)`, and 6599 `(width - 1, height - 1)` (inclusive), which are the top-left and 6600 bottom-right of the pixel array, respectively. The width and 6601 height dimensions are given in android.sensor.info.pixelArraySize. 6602 This may include hot pixels that lie outside of the active array 6603 bounds given by android.sensor.info.activeArraySize. 6604 </details> 6605 <hal_details> 6606 A hotpixel map contains the coordinates of pixels on the camera 6607 sensor that do report valid values (usually due to defects in 6608 the camera sensor). This includes pixels that are stuck at certain 6609 values, or have a response that does not accuractly encode the 6610 incoming light from the scene. 6611 6612 To avoid performance issues, there should be significantly fewer hot 6613 pixels than actual pixels on the camera sensor. 6614 </hal_details> 6615 <tag id="V1" /> 6616 <tag id="RAW" /> 6617 </entry> 6618 </dynamic> 6619 <controls> 6620 <entry name="lensShadingMapMode" type="byte" visibility="public" enum="true" hwlevel="full"> 6621 <enum> 6622 <value>OFF 6623 <notes>Do not include a lens shading map in the capture result.</notes></value> 6624 <value>ON 6625 <notes>Include a lens shading map in the capture result.</notes></value> 6626 </enum> 6627 <description>Whether the camera device will output the lens 6628 shading map in output result metadata.</description> 6629 <details>When set to ON, 6630 android.statistics.lensShadingMap will be provided in 6631 the output result metadata. 6632 6633 ON is always supported on devices with the RAW capability. 6634 </details> 6635 <tag id="RAW" /> 6636 </entry> 6637 </controls> 6638 <dynamic> 6639 <clone entry="android.statistics.lensShadingMapMode" kind="controls"> 6640 </clone> 6641 </dynamic> 6642 </section> 6643 <section name="tonemap"> 6644 <controls> 6645 <entry name="curveBlue" type="float" visibility="hidden" 6646 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 6647 container="array" hwlevel="full"> 6648 <array> 6649 <size>n</size> 6650 <size>2</size> 6651 </array> 6652 <description>Tonemapping / contrast / gamma curve for the blue 6653 channel, to use when android.tonemap.mode is 6654 CONTRAST_CURVE.</description> 6655 <details>See android.tonemap.curveRed for more details.</details> 6656 </entry> 6657 <entry name="curveGreen" type="float" visibility="hidden" 6658 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 6659 container="array" hwlevel="full"> 6660 <array> 6661 <size>n</size> 6662 <size>2</size> 6663 </array> 6664 <description>Tonemapping / contrast / gamma curve for the green 6665 channel, to use when android.tonemap.mode is 6666 CONTRAST_CURVE.</description> 6667 <details>See android.tonemap.curveRed for more details.</details> 6668 </entry> 6669 <entry name="curveRed" type="float" visibility="hidden" 6670 type_notes="1D array of float pairs (P_IN, P_OUT). The maximum number of pairs is specified by android.tonemap.maxCurvePoints." 6671 container="array" hwlevel="full"> 6672 <array> 6673 <size>n</size> 6674 <size>2</size> 6675 </array> 6676 <description>Tonemapping / contrast / gamma curve for the red 6677 channel, to use when android.tonemap.mode is 6678 CONTRAST_CURVE.</description> 6679 <range>0-1 on both input and output coordinates, normalized 6680 as a floating-point value such that 0 == black and 1 == white. 6681 </range> 6682 <details> 6683 Each channel's curve is defined by an array of control points: 6684 6685 android.tonemap.curveRed = 6686 [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ] 6687 2 <= N <= android.tonemap.maxCurvePoints 6688 6689 These are sorted in order of increasing `Pin`; it is 6690 required that input values 0.0 and 1.0 are included in the list to 6691 define a complete mapping. For input values between control points, 6692 the camera device must linearly interpolate between the control 6693 points. 6694 6695 Each curve can have an independent number of points, and the number 6696 of points can be less than max (that is, the request doesn't have to 6697 always provide a curve with number of points equivalent to 6698 android.tonemap.maxCurvePoints). 6699 6700 A few examples, and their corresponding graphical mappings; these 6701 only specify the red channel and the precision is limited to 4 6702 digits, for conciseness. 6703 6704 Linear mapping: 6705 6706 android.tonemap.curveRed = [ 0, 0, 1.0, 1.0 ] 6707 6708  6709 6710 Invert mapping: 6711 6712 android.tonemap.curveRed = [ 0, 1.0, 1.0, 0 ] 6713 6714  6715 6716 Gamma 1/2.2 mapping, with 16 control points: 6717 6718 android.tonemap.curveRed = [ 6719 0.0000, 0.0000, 0.0667, 0.2920, 0.1333, 0.4002, 0.2000, 0.4812, 6720 0.2667, 0.5484, 0.3333, 0.6069, 0.4000, 0.6594, 0.4667, 0.7072, 6721 0.5333, 0.7515, 0.6000, 0.7928, 0.6667, 0.8317, 0.7333, 0.8685, 6722 0.8000, 0.9035, 0.8667, 0.9370, 0.9333, 0.9691, 1.0000, 1.0000 ] 6723 6724  6725 6726 Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points: 6727 6728 android.tonemap.curveRed = [ 6729 0.0000, 0.0000, 0.0667, 0.2864, 0.1333, 0.4007, 0.2000, 0.4845, 6730 0.2667, 0.5532, 0.3333, 0.6125, 0.4000, 0.6652, 0.4667, 0.7130, 6731 0.5333, 0.7569, 0.6000, 0.7977, 0.6667, 0.8360, 0.7333, 0.8721, 6732 0.8000, 0.9063, 0.8667, 0.9389, 0.9333, 0.9701, 1.0000, 1.0000 ] 6733 6734  6735 </details> 6736 <hal_details> 6737 For good quality of mapping, at least 128 control points are 6738 preferred. 6739 6740 A typical use case of this would be a gamma-1/2.2 curve, with as many 6741 control points used as are available. 6742 </hal_details> 6743 </entry> 6744 <entry name="curve" type="float" visibility="public" synthetic="true" 6745 typedef="tonemapCurve" 6746 hwlevel="full"> 6747 <description>Tonemapping / contrast / gamma curve to use when android.tonemap.mode 6748 is CONTRAST_CURVE.</description> 6749 <details> 6750 The tonemapCurve consist of three curves for each of red, green, and blue 6751 channels respectively. The following example uses the red channel as an 6752 example. The same logic applies to green and blue channel. 6753 Each channel's curve is defined by an array of control points: 6754 6755 curveRed = 6756 [ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ] 6757 2 <= N <= android.tonemap.maxCurvePoints 6758 6759 These are sorted in order of increasing `Pin`; it is always 6760 guaranteed that input values 0.0 and 1.0 are included in the list to 6761 define a complete mapping. For input values between control points, 6762 the camera device must linearly interpolate between the control 6763 points. 6764 6765 Each curve can have an independent number of points, and the number 6766 of points can be less than max (that is, the request doesn't have to 6767 always provide a curve with number of points equivalent to 6768 android.tonemap.maxCurvePoints). 6769 6770 A few examples, and their corresponding graphical mappings; these 6771 only specify the red channel and the precision is limited to 4 6772 digits, for conciseness. 6773 6774 Linear mapping: 6775 6776 curveRed = [ (0, 0), (1.0, 1.0) ] 6777 6778  6779 6780 Invert mapping: 6781 6782 curveRed = [ (0, 1.0), (1.0, 0) ] 6783 6784  6785 6786 Gamma 1/2.2 mapping, with 16 control points: 6787 6788 curveRed = [ 6789 (0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812), 6790 (0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072), 6791 (0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685), 6792 (0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ] 6793 6794  6795 6796 Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points: 6797 6798 curveRed = [ 6799 (0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845), 6800 (0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130), 6801 (0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721), 6802 (0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ] 6803 6804  6805 </details> 6806 <hal_details> 6807 This entry is created by the framework from the curveRed, curveGreen and 6808 curveBlue entries. 6809 </hal_details> 6810 </entry> 6811 <entry name="mode" type="byte" visibility="public" enum="true" 6812 hwlevel="full"> 6813 <enum> 6814 <value>CONTRAST_CURVE 6815 <notes>Use the tone mapping curve specified in 6816 the android.tonemap.curve* entries. 6817 6818 All color enhancement and tonemapping must be disabled, except 6819 for applying the tonemapping curve specified by 6820 android.tonemap.curve. 6821 6822 Must not slow down frame rate relative to raw 6823 sensor output. 6824 </notes> 6825 </value> 6826 <value>FAST 6827 <notes> 6828 Advanced gamma mapping and color enhancement may be applied, without 6829 reducing frame rate compared to raw sensor output. 6830 </notes> 6831 </value> 6832 <value>HIGH_QUALITY 6833 <notes> 6834 High-quality gamma mapping and color enhancement will be applied, at 6835 the cost of reduced frame rate compared to raw sensor output. 6836 </notes> 6837 </value> 6838 </enum> 6839 <description>High-level global contrast/gamma/tonemapping control. 6840 </description> 6841 <range>android.tonemap.availableToneMapModes</range> 6842 <details> 6843 When switching to an application-defined contrast curve by setting 6844 android.tonemap.mode to CONTRAST_CURVE, the curve is defined 6845 per-channel with a set of `(in, out)` points that specify the 6846 mapping from input high-bit-depth pixel value to the output 6847 low-bit-depth value. Since the actual pixel ranges of both input 6848 and output may change depending on the camera pipeline, the values 6849 are specified by normalized floating-point numbers. 6850 6851 More-complex color mapping operations such as 3D color look-up 6852 tables, selective chroma enhancement, or other non-linear color 6853 transforms will be disabled when android.tonemap.mode is 6854 CONTRAST_CURVE. 6855 6856 When using either FAST or HIGH_QUALITY, the camera device will 6857 emit its own tonemap curve in android.tonemap.curve. 6858 These values are always available, and as close as possible to the 6859 actually used nonlinear/nonglobal transforms. 6860 6861 If a request is sent with CONTRAST_CURVE with the camera device's 6862 provided curve in FAST or HIGH_QUALITY, the image's tonemap will be 6863 roughly the same.</details> 6864 </entry> 6865 </controls> 6866 <static> 6867 <entry name="maxCurvePoints" type="int32" visibility="public" 6868 hwlevel="full"> 6869 <description>Maximum number of supported points in the 6870 tonemap curve that can be used for android.tonemap.curve. 6871 </description> 6872 <details> 6873 If the actual number of points provided by the application (in android.tonemap.curve*) is 6874 less than this maximum, the camera device will resample the curve to its internal 6875 representation, using linear interpolation. 6876 6877 The output curves in the result metadata may have a different number 6878 of points than the input curves, and will represent the actual 6879 hardware curves used as closely as possible when linearly interpolated. 6880 </details> 6881 <hal_details> 6882 This value must be at least 64. This should be at least 128. 6883 </hal_details> 6884 </entry> 6885 <entry name="availableToneMapModes" type="byte" visibility="public" 6886 type_notes="list of enums" container="array" typedef="enumList" hwlevel="full"> 6887 <array> 6888 <size>n</size> 6889 </array> 6890 <description> 6891 List of tonemapping modes for android.tonemap.mode that are supported by this camera 6892 device. 6893 </description> 6894 <range>Any value listed in android.tonemap.mode</range> 6895 <details> 6896 Camera devices that support the MANUAL_POST_PROCESSING capability will always list 6897 CONTRAST_CURVE and FAST. This includes all FULL level devices. 6898 </details> 6899 </entry> 6900 </static> 6901 <dynamic> 6902 <clone entry="android.tonemap.curveBlue" kind="controls"> 6903 </clone> 6904 <clone entry="android.tonemap.curveGreen" kind="controls"> 6905 </clone> 6906 <clone entry="android.tonemap.curveRed" kind="controls"> 6907 </clone> 6908 <clone entry="android.tonemap.curve" kind="controls"> 6909 </clone> 6910 <clone entry="android.tonemap.mode" kind="controls"> 6911 </clone> 6912 </dynamic> 6913 </section> 6914 <section name="led"> 6915 <controls> 6916 <entry name="transmit" type="byte" visibility="hidden" optional="true" 6917 enum="true" typedef="boolean"> 6918 <enum> 6919 <value>OFF</value> 6920 <value>ON</value> 6921 </enum> 6922 <description>This LED is nominally used to indicate to the user 6923 that the camera is powered on and may be streaming images back to the 6924 Application Processor. In certain rare circumstances, the OS may 6925 disable this when video is processed locally and not transmitted to 6926 any untrusted applications. 6927 6928 In particular, the LED *must* always be on when the data could be 6929 transmitted off the device. The LED *should* always be on whenever 6930 data is stored locally on the device. 6931 6932 The LED *may* be off if a trusted application is using the data that 6933 doesn't violate the above rules. 6934 </description> 6935 </entry> 6936 </controls> 6937 <dynamic> 6938 <clone entry="android.led.transmit" kind="controls"></clone> 6939 </dynamic> 6940 <static> 6941 <entry name="availableLeds" type="byte" visibility="hidden" optional="true" 6942 enum="true" 6943 container="array"> 6944 <array> 6945 <size>n</size> 6946 </array> 6947 <enum> 6948 <value>TRANSMIT 6949 <notes>android.led.transmit control is used.</notes> 6950 </value> 6951 </enum> 6952 <description>A list of camera LEDs that are available on this system. 6953 </description> 6954 </entry> 6955 </static> 6956 </section> 6957 <section name="info"> 6958 <static> 6959 <entry name="supportedHardwareLevel" type="byte" visibility="public" 6960 enum="true" hwlevel="legacy"> 6961 <enum> 6962 <value> 6963 LIMITED 6964 <notes> 6965 This camera device has only limited capabilities. 6966 </notes> 6967 </value> 6968 <value> 6969 FULL 6970 <notes> 6971 This camera device is capable of supporting advanced imaging applications. 6972 </notes> 6973 </value> 6974 <value> 6975 LEGACY 6976 <notes> 6977 This camera device is running in backward compatibility mode. 6978 </notes> 6979 </value> 6980 </enum> 6981 <description> 6982 Generally classifies the overall set of the camera device functionality. 6983 </description> 6984 <details> 6985 Camera devices will come in three flavors: LEGACY, LIMITED and FULL. 6986 6987 A FULL device will support below capabilities: 6988 6989 * 30fps operation at maximum resolution (== sensor resolution) is preferred, more than 6990 20fps is required, for at least uncompressed YUV 6991 output. (android.request.availableCapabilities contains BURST_CAPTURE) 6992 * Per frame control (android.sync.maxLatency `==` PER_FRAME_CONTROL) 6993 * Manual sensor control (android.request.availableCapabilities contains MANUAL_SENSOR) 6994 * Manual post-processing control (android.request.availableCapabilities contains 6995 MANUAL_POST_PROCESSING) 6996 * Arbitrary cropping region (android.scaler.croppingType `==` FREEFORM) 6997 * At least 3 processed (but not stalling) format output streams 6998 (android.request.maxNumOutputProc `>=` 3) 6999 * The required stream configuration defined in android.scaler.availableStreamConfigurations 7000 * The required exposure time range defined in android.sensor.info.exposureTimeRange 7001 * The required maxFrameDuration defined in android.sensor.info.maxFrameDuration 7002 7003 A LIMITED device may have some or none of the above characteristics. 7004 To find out more refer to android.request.availableCapabilities. 7005 7006 Some features are not part of any particular hardware level or capability and must be 7007 queried separately. These include: 7008 7009 * Calibrated timestamps (android.sensor.info.timestampSource `==` REALTIME) 7010 * Precision lens control (android.lens.info.focusDistanceCalibration `==` CALIBRATED) 7011 * Face detection (android.statistics.info.availableFaceDetectModes) 7012 * Optical or electrical image stabilization 7013 (android.lens.info.availableOpticalStabilization, 7014 android.control.availableVideoStabilizationModes) 7015 7016 A LEGACY device does not support per-frame control, manual sensor control, manual 7017 post-processing, arbitrary cropping regions, and has relaxed performance constraints. 7018 7019 Each higher level supports everything the lower level supports 7020 in this order: FULL `>` LIMITED `>` LEGACY. 7021 </details> 7022 <hal_details> 7023 The camera 3 HAL device can implement one of two possible 7024 operational modes; limited and full. Full support is 7025 expected from new higher-end devices. Limited mode has 7026 hardware requirements roughly in line with those for a 7027 camera HAL device v1 implementation, and is expected from 7028 older or inexpensive devices. Full is a strict superset of 7029 limited, and they share the same essential operational flow. 7030 7031 For full details refer to "S3. Operational Modes" in camera3.h 7032 7033 Camera HAL3+ must not implement LEGACY mode. It is there 7034 for backwards compatibility in the `android.hardware.camera2` 7035 user-facing API only. 7036 </hal_details> 7037 </entry> 7038 </static> 7039 </section> 7040 <section name="blackLevel"> 7041 <controls> 7042 <entry name="lock" type="byte" visibility="public" enum="true" 7043 typedef="boolean" hwlevel="full"> 7044 <enum> 7045 <value>OFF</value> 7046 <value>ON</value> 7047 </enum> 7048 <description> Whether black-level compensation is locked 7049 to its current values, or is free to vary.</description> 7050 <details>When set to `true` (ON), the values used for black-level 7051 compensation will not change until the lock is set to 7052 `false` (OFF). 7053 7054 Since changes to certain capture parameters (such as 7055 exposure time) may require resetting of black level 7056 compensation, the camera device must report whether setting 7057 the black level lock was successful in the output result 7058 metadata. 7059 7060 For example, if a sequence of requests is as follows: 7061 7062 * Request 1: Exposure = 10ms, Black level lock = OFF 7063 * Request 2: Exposure = 10ms, Black level lock = ON 7064 * Request 3: Exposure = 10ms, Black level lock = ON 7065 * Request 4: Exposure = 20ms, Black level lock = ON 7066 * Request 5: Exposure = 20ms, Black level lock = ON 7067 * Request 6: Exposure = 20ms, Black level lock = ON 7068 7069 And the exposure change in Request 4 requires the camera 7070 device to reset the black level offsets, then the output 7071 result metadata is expected to be: 7072 7073 * Result 1: Exposure = 10ms, Black level lock = OFF 7074 * Result 2: Exposure = 10ms, Black level lock = ON 7075 * Result 3: Exposure = 10ms, Black level lock = ON 7076 * Result 4: Exposure = 20ms, Black level lock = OFF 7077 * Result 5: Exposure = 20ms, Black level lock = ON 7078 * Result 6: Exposure = 20ms, Black level lock = ON 7079 7080 This indicates to the application that on frame 4, black 7081 levels were reset due to exposure value changes, and pixel 7082 values may not be consistent across captures. 7083 7084 The camera device will maintain the lock to the extent 7085 possible, only overriding the lock to OFF when changes to 7086 other request parameters require a black level recalculation 7087 or reset. 7088 </details> 7089 <hal_details> 7090 If for some reason black level locking is no longer possible 7091 (for example, the analog gain has changed, which forces 7092 black level offsets to be recalculated), then the HAL must 7093 override this request (and it must report 'OFF' when this 7094 does happen) until the next capture for which locking is 7095 possible again.</hal_details> 7096 <tag id="HAL2" /> 7097 </entry> 7098 </controls> 7099 <dynamic> 7100 <clone entry="android.blackLevel.lock" 7101 kind="controls"> 7102 <details> 7103 Whether the black level offset was locked for this frame. Should be 7104 ON if android.blackLevel.lock was ON in the capture request, unless 7105 a change in other capture settings forced the camera device to 7106 perform a black level reset. 7107 </details> 7108 </clone> 7109 </dynamic> 7110 </section> 7111 <section name="sync"> 7112 <dynamic> 7113 <entry name="frameNumber" type="int64" visibility="hidden" enum="true" 7114 hwlevel="legacy"> 7115 <enum> 7116 <value id="-1">CONVERGING 7117 <notes> 7118 The current result is not yet fully synchronized to any request. 7119 7120 Synchronization is in progress, and reading metadata from this 7121 result may include a mix of data that have taken effect since the 7122 last synchronization time. 7123 7124 In some future result, within android.sync.maxLatency frames, 7125 this value will update to the actual frame number frame number 7126 the result is guaranteed to be synchronized to (as long as the 7127 request settings remain constant). 7128 </notes> 7129 </value> 7130 <value id="-2">UNKNOWN 7131 <notes> 7132 The current result's synchronization status is unknown. 7133 7134 The result may have already converged, or it may be in 7135 progress. Reading from this result may include some mix 7136 of settings from past requests. 7137 7138 After a settings change, the new settings will eventually all 7139 take effect for the output buffers and results. However, this 7140 value will not change when that happens. Altering settings 7141 rapidly may provide outcomes using mixes of settings from recent 7142 requests. 7143 7144 This value is intended primarily for backwards compatibility with 7145 the older camera implementations (for android.hardware.Camera). 7146 </notes> 7147 </value> 7148 </enum> 7149 <description>The frame number corresponding to the last request 7150 with which the output result (metadata + buffers) has been fully 7151 synchronized.</description> 7152 <range>Either a non-negative value corresponding to a 7153 `frame_number`, or one of the two enums (CONVERGING / UNKNOWN). 7154 </range> 7155 <details> 7156 When a request is submitted to the camera device, there is usually a 7157 delay of several frames before the controls get applied. A camera 7158 device may either choose to account for this delay by implementing a 7159 pipeline and carefully submit well-timed atomic control updates, or 7160 it may start streaming control changes that span over several frame 7161 boundaries. 7162 7163 In the latter case, whenever a request's settings change relative to 7164 the previous submitted request, the full set of changes may take 7165 multiple frame durations to fully take effect. Some settings may 7166 take effect sooner (in less frame durations) than others. 7167 7168 While a set of control changes are being propagated, this value 7169 will be CONVERGING. 7170 7171 Once it is fully known that a set of control changes have been 7172 finished propagating, and the resulting updated control settings 7173 have been read back by the camera device, this value will be set 7174 to a non-negative frame number (corresponding to the request to 7175 which the results have synchronized to). 7176 7177 Older camera device implementations may not have a way to detect 7178 when all camera controls have been applied, and will always set this 7179 value to UNKNOWN. 7180 7181 FULL capability devices will always have this value set to the 7182 frame number of the request corresponding to this result. 7183 7184 _Further details_: 7185 7186 * Whenever a request differs from the last request, any future 7187 results not yet returned may have this value set to CONVERGING (this 7188 could include any in-progress captures not yet returned by the camera 7189 device, for more details see pipeline considerations below). 7190 * Submitting a series of multiple requests that differ from the 7191 previous request (e.g. r1, r2, r3 s.t. r1 != r2 != r3) 7192 moves the new synchronization frame to the last non-repeating 7193 request (using the smallest frame number from the contiguous list of 7194 repeating requests). 7195 * Submitting the same request repeatedly will not change this value 7196 to CONVERGING, if it was already a non-negative value. 7197 * When this value changes to non-negative, that means that all of the 7198 metadata controls from the request have been applied, all of the 7199 metadata controls from the camera device have been read to the 7200 updated values (into the result), and all of the graphics buffers 7201 corresponding to this result are also synchronized to the request. 7202 7203 _Pipeline considerations_: 7204 7205 Submitting a request with updated controls relative to the previously 7206 submitted requests may also invalidate the synchronization state 7207 of all the results corresponding to currently in-flight requests. 7208 7209 In other words, results for this current request and up to 7210 android.request.pipelineMaxDepth prior requests may have their 7211 android.sync.frameNumber change to CONVERGING. 7212 </details> 7213 <hal_details> 7214 Using UNKNOWN here is illegal unless android.sync.maxLatency 7215 is also UNKNOWN. 7216 7217 FULL capability devices should simply set this value to the 7218 `frame_number` of the request this result corresponds to. 7219 </hal_details> 7220 <tag id="V1" /> 7221 </entry> 7222 </dynamic> 7223 <static> 7224 <entry name="maxLatency" type="int32" visibility="public" enum="true" 7225 hwlevel="legacy"> 7226 <enum> 7227 <value id="0">PER_FRAME_CONTROL 7228 <notes> 7229 Every frame has the requests immediately applied. 7230 7231 Furthermore for all results, 7232 `android.sync.frameNumber == CaptureResult#getFrameNumber()` 7233 7234 Changing controls over multiple requests one after another will 7235 produce results that have those controls applied atomically 7236 each frame. 7237 7238 All FULL capability devices will have this as their maxLatency. 7239 </notes> 7240 </value> 7241 <value id="-1">UNKNOWN 7242 <notes> 7243 Each new frame has some subset (potentially the entire set) 7244 of the past requests applied to the camera settings. 7245 7246 By submitting a series of identical requests, the camera device 7247 will eventually have the camera settings applied, but it is 7248 unknown when that exact point will be. 7249 7250 All LEGACY capability devices will have this as their maxLatency. 7251 </notes> 7252 </value> 7253 </enum> 7254 <description> 7255 The maximum number of frames that can occur after a request 7256 (different than the previous) has been submitted, and before the 7257 result's state becomes synchronized (by setting 7258 android.sync.frameNumber to a non-negative value). 7259 </description> 7260 <units>Frame counts</units> 7261 <range>A positive value, PER_FRAME_CONTROL, or UNKNOWN.</range> 7262 <details> 7263 This defines the maximum distance (in number of metadata results), 7264 between android.sync.frameNumber and the equivalent 7265 frame number for that result. 7266 7267 In other words this acts as an upper boundary for how many frames 7268 must occur before the camera device knows for a fact that the new 7269 submitted camera settings have been applied in outgoing frames. 7270 7271 For example if the distance was 2, 7272 7273 initial request = X (repeating) 7274 request1 = X 7275 request2 = Y 7276 request3 = Y 7277 request4 = Y 7278 7279 where requestN has frameNumber N, and the first of the repeating 7280 initial request's has frameNumber F (and F < 1). 7281 7282 initial result = X' + { android.sync.frameNumber == F } 7283 result1 = X' + { android.sync.frameNumber == F } 7284 result2 = X' + { android.sync.frameNumber == CONVERGING } 7285 result3 = X' + { android.sync.frameNumber == CONVERGING } 7286 result4 = X' + { android.sync.frameNumber == 2 } 7287 7288 where resultN has frameNumber N. 7289 7290 Since `result4` has a `frameNumber == 4` and 7291 `android.sync.frameNumber == 2`, the distance is clearly 7292 `4 - 2 = 2`. 7293 </details> 7294 <hal_details> 7295 Use `frame_count` from camera3_request_t instead of 7296 android.request.frameCount or `CaptureResult#getFrameNumber()`. 7297 7298 LIMITED devices are strongly encouraged to use a non-negative 7299 value. If UNKNOWN is used here then app developers do not have a way 7300 to know when sensor settings have been applied. 7301 </hal_details> 7302 <tag id="V1" /> 7303 </entry> 7304 </static> 7305 </section> 7306 </namespace> 7307 </metadata> 7308
