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