CameraMetadata: Docs cleanup, especially units and range

- Add entries for units and range into javadoc
- Fix up existing units entries and add new ones
- Fix up range entries to be consistent for enums
- Add range entries where it makes sense
- Minor fix to javadoc gen to allow for code indentation
- Lots of edits for consistency, especially to
  available* entries.

Bug: 16525650
Change-Id: I654d86c66e796e87d2cf3b47ffcc72cd26977e43

4 files changed, 1521 insertions, 1040 deletions

diff --git a/camera/docs/CameraMetadataKeys.mako b/camera/docs/CameraMetadataKeys.mako
index 989a35e2..f9286fa7 100644
--- a/camera/docs/CameraMetadataKeys.mako
+++ b/camera/docs/CameraMetadataKeys.mako
@@ -24,28 +24,6 @@
      * modify the comment blocks at the start or end.
      *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
 
-<%!
-  ##
-  ## Generate extra text blocks for the details field
-  def generate_extra_detail(entry):
-    def inner(text):
-      if entry.hwlevel != 'legacy': # covers any of (None, 'limited', 'full')
-        text += '\n\n<b>Optional</b> - This value may be {@code null} on some devices.\n'
-      if entry.hwlevel == 'full':
-        text += \
-          '\n<b>Full capability</b> - \n' + \
-          'Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the\n' + \
-          'android.info.supportedHardwareLevel key\n'
-      if entry.hwlevel == 'limited':
-        text += \
-          '\n<b>Limited capability</b> - \n' + \
-          'Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the\n' + \
-          'android.info.supportedHardwareLevel key\n'
-      if entry.hwlevel == 'legacy':
-        text += "\nThis key is available on all devices."
-      return text
-    return inner
-%>
 ##
 ## Generate a single key and docs
 <%def name="generate_key(entry)">\
@@ -59,7 +37,7 @@
     if entry.details:
         details = dedent(entry.details)
     # Unconditionally add extra information if necessary
-    extra_detail = generate_extra_detail(entry)("")
+    extra_detail = generate_extra_javadoc_detail(entry)("")
 
     concatenated_info = description + details + extra_detail
 %>\
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 54a48314..c9ae10fd 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -1228,6 +1228,7 @@ from sensor RGB color space to output linear sRGB color space.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Unitless scale factors
             </td>
 
             <td class="entry_range">
@@ -1288,6 +1289,7 @@ white-balance.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Unitless gain factors
             </td>
 
             <td class="entry_range">
@@ -1373,6 +1375,7 @@ capture rate (relative to sensor raw output).<wbr/></p></span>
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.colorCorrection.availableAberrationModes">android.<wbr/>color<wbr/>Correction.<wbr/>available<wbr/>Aberration<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -1384,9 +1387,7 @@ capture rate (relative to sensor raw output).<wbr/></p></span>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This must be set to a valid mode from
-<a href="#static_android.colorCorrection.availableAberrationModes">android.<wbr/>color<wbr/>Correction.<wbr/>available<wbr/>Aberration<wbr/>Modes</a>.<wbr/></p>
-<p>Chromatic (color) aberration is caused by the fact that different wavelengths of light
+              <p>Chromatic (color) aberration is caused by the fact that different wavelengths of light
 can not focus on the same point after exiting from the lens.<wbr/> This metadata defines
 the high level control of chromatic aberration correction algorithm,<wbr/> which aims to
 minimize the chromatic artifacts that may occur along the object boundaries in an
@@ -1578,6 +1579,7 @@ from sensor RGB color space to output linear sRGB color space.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Unitless scale factors
             </td>
 
             <td class="entry_range">
@@ -1638,6 +1640,7 @@ white-balance.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Unitless gain factors
             </td>
 
             <td class="entry_range">
@@ -1723,6 +1726,7 @@ capture rate (relative to sensor raw output).<wbr/></p></span>
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.colorCorrection.availableAberrationModes">android.<wbr/>color<wbr/>Correction.<wbr/>available<wbr/>Aberration<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -1734,9 +1738,7 @@ capture rate (relative to sensor raw output).<wbr/></p></span>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This must be set to a valid mode from
-<a href="#static_android.colorCorrection.availableAberrationModes">android.<wbr/>color<wbr/>Correction.<wbr/>available<wbr/>Aberration<wbr/>Modes</a>.<wbr/></p>
-<p>Chromatic (color) aberration is caused by the fact that different wavelengths of light
+              <p>Chromatic (color) aberration is caused by the fact that different wavelengths of light
 can not focus on the same point after exiting from the lens.<wbr/> This metadata defines
 the high level control of chromatic aberration correction algorithm,<wbr/> which aims to
 minimize the chromatic artifacts that may occur along the object boundaries in an
@@ -1806,15 +1808,15 @@ applying aberration correction.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The set of aberration correction modes supported by this camera device.<wbr/></p>
+              <p>List of aberration correction modes for <a href="#controls_android.colorCorrection.aberrationMode">android.<wbr/>color<wbr/>Correction.<wbr/>aberration<wbr/>Mode</a> that are
+supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
-              <p>The subset of aberration correction mode from those specified in
-<a href="#controls_android.colorCorrection.aberrationMode">android.<wbr/>color<wbr/>Correction.<wbr/>aberration<wbr/>Mode</a>.<wbr/></p>
+              <p>Any value listed in <a href="#controls_android.colorCorrection.aberrationMode">android.<wbr/>color<wbr/>Correction.<wbr/>aberration<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -1829,11 +1831,11 @@ applying aberration correction.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This metadata lists the valid modes for <a href="#controls_android.colorCorrection.aberrationMode">android.<wbr/>color<wbr/>Correction.<wbr/>aberration<wbr/>Mode</a>.<wbr/>
-If no aberration correction modes are available for a device,<wbr/> this list will solely include
+              <p>This key lists the valid modes for <a href="#controls_android.colorCorrection.aberrationMode">android.<wbr/>color<wbr/>Correction.<wbr/>aberration<wbr/>Mode</a>.<wbr/>  If no
+aberration correction modes are available for a device,<wbr/> this list will solely include
 OFF mode.<wbr/></p>
-<p>For FULL capability device (<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> <code>==</code> FULL),<wbr/> OFF must be
-included.<wbr/></p>
+<p>For FULL capability device (<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> <code>==</code> FULL),<wbr/> OFF is
+always included.<wbr/></p>
 <p>LEGACY devices will always only support FAST mode.<wbr/></p>
             </td>
           </tr>
@@ -1960,7 +1962,7 @@ control.<wbr/></p>
 options for the antibanding mode.<wbr/> The
 <a href="#static_android.control.aeAvailableAntibandingModes">android.<wbr/>control.<wbr/>ae<wbr/>Available<wbr/>Antibanding<wbr/>Modes</a> key contains
 the available modes for a given camera device.<wbr/></p>
-<p>The default mode is AUTO,<wbr/> which must be supported by all
+<p>The default mode is AUTO,<wbr/> which is supported by all
 camera devices.<wbr/></p>
 <p>If manual exposure control is enabled (by setting
 <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> or <a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> to OFF),<wbr/>
@@ -2014,7 +2016,7 @@ brightness.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              count of positive/<wbr/>negative EV steps
+              Compensation steps
             </td>
 
             <td class="entry_range">
@@ -2114,9 +2116,11 @@ calculated values.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Note that even when AE is locked,<wbr/> the flash may be
-fired if the <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> is ON_<wbr/>AUTO_<wbr/>FLASH /<wbr/> ON_<wbr/>ALWAYS_<wbr/>FLASH /<wbr/>
-ON_<wbr/>AUTO_<wbr/>FLASH_<wbr/>REDEYE.<wbr/></p>
+              <p>When set to <code>true</code> (ON),<wbr/> the AE algorithm is locked to its latest parameters,<wbr/>
+and will not change exposure settings until the lock is set to <code>false</code> (OFF).<wbr/></p>
+<p>Note that even when AE is locked,<wbr/> the flash may be fired if
+the <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> is ON_<wbr/>AUTO_<wbr/>FLASH /<wbr/>
+ON_<wbr/>ALWAYS_<wbr/>FLASH /<wbr/> ON_<wbr/>AUTO_<wbr/>FLASH_<wbr/>REDEYE.<wbr/></p>
 <p>When <a href="#controls_android.control.aeExposureCompensation">android.<wbr/>control.<wbr/>ae<wbr/>Exposure<wbr/>Compensation</a> is changed,<wbr/> even if the AE lock
 is ON,<wbr/> the camera device will still adjust its exposure value.<wbr/></p>
 <p>If AE precapture is triggered (see <a href="#controls_android.control.aePrecaptureTrigger">android.<wbr/>control.<wbr/>ae<wbr/>Precapture<wbr/>Trigger</a>)
@@ -2125,6 +2129,19 @@ when AE is already locked,<wbr/> the camera device will not change the exposure
 parameters.<wbr/> The flash may be fired if the <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a>
 is ON_<wbr/>AUTO_<wbr/>FLASH/<wbr/>ON_<wbr/>AUTO_<wbr/>FLASH_<wbr/>REDEYE and the scene is too dark.<wbr/> If the
 <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> is ON_<wbr/>ALWAYS_<wbr/>FLASH,<wbr/> the scene may become overexposed.<wbr/></p>
+<p>Since the camera device has a pipeline of in-flight requests,<wbr/> the settings that
+get locked do not necessarily correspond to the settings that were present in the
+latest capture result received from the camera device,<wbr/> since additional captures
+and AE updates may have occurred even before the result was sent out.<wbr/> If an
+application is switching between automatic and manual control and wishes to eliminate
+any flicker during the switch,<wbr/> the following procedure is recommended:</p>
+<ol>
+<li>Starting in auto-AE mode:</li>
+<li>Lock AE</li>
+<li>Wait for the first result to be output that has the AE locked</li>
+<li>Copy exposure settings from that result into a request,<wbr/> set the request to manual AE</li>
+<li>Submit the capture request,<wbr/> proceed to run manual AE as desired.<wbr/></li>
+</ol>
 <p>See <a href="#dynamic_android.control.aeState">android.<wbr/>control.<wbr/>ae<wbr/>State</a> for AE lock related state transition details.<wbr/></p>
             </td>
           </tr>
@@ -2278,15 +2295,16 @@ CaptureResult.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of areas to use for
-metering.<wbr/></p>
+              <p>List of metering areas to use for auto-exposure adjustment.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
             </td>
 
             <td class="entry_range">
-              <p><code>area_<wbr/>count &lt;= <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a></code></p>
+              <p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
             </td>
 
             <td class="entry_tags">
@@ -2301,23 +2319,30 @@ metering.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Optional.<wbr/> Not available if <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a> is 0.<wbr/>
+              <p>Not available if <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a> is 0.<wbr/>
 Otherwise will always be present.<wbr/></p>
+<p>The maximum number of regions supported by the device is determined by the value
+of <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a>.<wbr/></p>
 <p>The coordinate system is based on the active pixel array,<wbr/>
 with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
 (<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
 <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
 bottom-right pixel in the active pixel array.<wbr/></p>
-<p>The weight must range from 0 to 1000,<wbr/> and represents a weight
+<p>The weight must be within <code>[0,<wbr/> 1000]</code>,<wbr/> and represents a weight
 for every pixel in the area.<wbr/> This means that a large metering area
 with the same weight as a smaller area will have more effect in
 the metering result.<wbr/> Metering areas can partially overlap and the
 camera device will add the weights in the overlap region.<wbr/></p>
-<p>If all regions have 0 weight,<wbr/> then no specific metering area
-needs to be used by the camera device.<wbr/> If the metering region is
-outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in capture result metadata,<wbr/>
-the camera device will ignore the sections outside the region and output the
-used sections in the result metadata.<wbr/></p>
+<p>The weights are relative to weights of other exposure metering regions,<wbr/> so if only one
+region is used,<wbr/> all non-zero weights will have the same effect.<wbr/> A region with 0
+weight is ignored.<wbr/></p>
+<p>If all regions have 0 weight,<wbr/> then no specific metering area needs to be used by the
+camera device.<wbr/></p>
+<p>If the metering region is outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in
+capture result metadata,<wbr/> the camera device will ignore the sections outside the crop
+region and output only the intersection rectangle as the metering region in the result
+metadata.<wbr/>  If the region is entirely outside the crop region,<wbr/> it will be ignored and
+not reported in the result metadata.<wbr/></p>
             </td>
           </tr>
 
@@ -2362,15 +2387,17 @@ exclusive on xmax and ymax.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Range over which fps can be adjusted to
-maintain exposure.<wbr/></p>
+              <p>Range over which the auto-exposure routine can
+adjust the capture frame rate to maintain good
+exposure.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Frames per second (FPS)
             </td>
 
             <td class="entry_range">
-              <p><a href="#static_android.control.aeAvailableTargetFpsRanges">android.<wbr/>control.<wbr/>ae<wbr/>Available<wbr/>Target<wbr/>Fps<wbr/>Ranges</a></p>
+              <p>Any of the entries in <a href="#static_android.control.aeAvailableTargetFpsRanges">android.<wbr/>control.<wbr/>ae<wbr/>Available<wbr/>Target<wbr/>Fps<wbr/>Ranges</a></p>
             </td>
 
             <td class="entry_tags">
@@ -2386,7 +2413,8 @@ maintain exposure.<wbr/></p>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
               <p>Only constrains auto-exposure (AE) algorithm,<wbr/> not
-manual control of <a href="#controls_android.sensor.exposureTime">android.<wbr/>sensor.<wbr/>exposure<wbr/>Time</a></p>
+manual control of <a href="#controls_android.sensor.exposureTime">android.<wbr/>sensor.<wbr/>exposure<wbr/>Time</a> and
+<a href="#controls_android.sensor.frameDuration">android.<wbr/>sensor.<wbr/>frame<wbr/>Duration</a>.<wbr/></p>
             </td>
           </tr>
 
@@ -2465,6 +2493,10 @@ sequence completes before starting a new one.<wbr/></p>
 depends on the current AE mode and state; see
 <a href="#dynamic_android.control.aeState">android.<wbr/>control.<wbr/>ae<wbr/>State</a> for AE precapture state transition
 details.<wbr/></p>
+<p>On LEGACY-level devices,<wbr/> the precapture trigger is not supported;
+capturing a high-resolution JPEG image will automatically trigger a
+precapture sequence before the high-resolution capture,<wbr/> including
+potentially firing a pre-capture flash.<wbr/></p>
             </td>
           </tr>
 
@@ -2661,15 +2693,16 @@ that will arise on camera modules with open-loop VCMs.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of areas to use for focus
-estimation.<wbr/></p>
+              <p>List of metering areas to use for auto-focus.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
             </td>
 
             <td class="entry_range">
-              <p><code>area_<wbr/>count &lt;= <a href="#static_android.control.maxRegions">android.<wbr/>control.<wbr/>max<wbr/>Regions</a>[2]</code></p>
+              <p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
             </td>
 
             <td class="entry_tags">
@@ -2684,23 +2717,30 @@ estimation.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Optional.<wbr/> Not available if <a href="#static_android.control.maxRegionsAf">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Af</a> is 0.<wbr/>
+              <p>Not available if <a href="#static_android.control.maxRegionsAf">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Af</a> is 0.<wbr/>
 Otherwise will always be present.<wbr/></p>
+<p>The maximum number of focus areas supported by the device is determined by the value
+of <a href="#static_android.control.maxRegionsAf">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Af</a>.<wbr/></p>
 <p>The coordinate system is based on the active pixel array,<wbr/>
 with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
 (<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
 <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
 bottom-right pixel in the active pixel array.<wbr/></p>
-<p>The weight must range from 0 to 1000,<wbr/> and represents a weight
+<p>The weight must be within <code>[0,<wbr/> 1000]</code>,<wbr/> and represents a weight
 for every pixel in the area.<wbr/> This means that a large metering area
 with the same weight as a smaller area will have more effect in
 the metering result.<wbr/> Metering areas can partially overlap and the
 camera device will add the weights in the overlap region.<wbr/></p>
-<p>If all regions have 0 weight,<wbr/> then no specific metering area
-needs to be used by the camera device.<wbr/> If the metering region is
-outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in capture result metadata,<wbr/>
-the camera device will ignore the sections outside the region and output the
-used sections in the result metadata.<wbr/></p>
+<p>The weights are relative to weights of other metering regions,<wbr/> so if only one region
+is used,<wbr/> all non-zero weights will have the same effect.<wbr/> A region with 0 weight is
+ignored.<wbr/></p>
+<p>If all regions have 0 weight,<wbr/> then no specific metering area needs to be used by the
+camera device.<wbr/></p>
+<p>If the metering region is outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in
+capture result metadata,<wbr/> the camera device will ignore the sections outside the crop
+region and output only the intersection rectangle as the metering region in the result
+metadata.<wbr/> If the region is entirely outside the crop region,<wbr/> it will be ignored and
+not reported in the result metadata.<wbr/></p>
             </td>
           </tr>
 
@@ -2851,7 +2891,22 @@ latest calculated values.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Note that AWB lock is only meaningful when
+              <p>When set to <code>true</code> (ON),<wbr/> the AWB algorithm is locked to its latest parameters,<wbr/>
+and will not change color balance settings until the lock is set to <code>false</code> (OFF).<wbr/></p>
+<p>Since the camera device has a pipeline of in-flight requests,<wbr/> the settings that
+get locked do not necessarily correspond to the settings that were present in the
+latest capture result received from the camera device,<wbr/> since additional captures
+and AWB updates may have occurred even before the result was sent out.<wbr/> If an
+application is switching between automatic and manual control and wishes to eliminate
+any flicker during the switch,<wbr/> the following procedure is recommended:</p>
+<ol>
+<li>Starting in auto-AWB mode:</li>
+<li>Lock AWB</li>
+<li>Wait for the first result to be output that has the AWB locked</li>
+<li>Copy AWB settings from that result into a request,<wbr/> set the request to manual AWB</li>
+<li>Submit the capture request,<wbr/> proceed to run manual AWB as desired.<wbr/></li>
+</ol>
+<p>Note that AWB lock is only meaningful when
 <a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a> is in the AUTO mode; in other modes,<wbr/>
 AWB is already fixed to a specific setting.<wbr/></p>
 <p>Some LEGACY devices may not support ON; the value is then overridden to OFF.<wbr/></p>
@@ -3060,15 +3115,17 @@ adjustment.<wbr/> The application's values for
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of areas to use for illuminant
+              <p>List of metering areas to use for auto-white-balance illuminant
 estimation.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
             </td>
 
             <td class="entry_range">
-              <p><code>area_<wbr/>count &lt;= <a href="#static_android.control.maxRegions">android.<wbr/>control.<wbr/>max<wbr/>Regions</a>[1]</code></p>
+              <p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
             </td>
 
             <td class="entry_tags">
@@ -3083,8 +3140,10 @@ estimation.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Optional.<wbr/> Not available if <a href="#static_android.control.maxRegionsAwb">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Awb</a> is 0.<wbr/>
+              <p>Not available if <a href="#static_android.control.maxRegionsAwb">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Awb</a> is 0.<wbr/>
 Otherwise will always be present.<wbr/></p>
+<p>The maximum number of regions supported by the device is determined by the value
+of <a href="#static_android.control.maxRegionsAwb">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Awb</a>.<wbr/></p>
 <p>The coordinate system is based on the active pixel array,<wbr/>
 with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
 (<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
@@ -3095,11 +3154,16 @@ for every pixel in the area.<wbr/> This means that a large metering area
 with the same weight as a smaller area will have more effect in
 the metering result.<wbr/> Metering areas can partially overlap and the
 camera device will add the weights in the overlap region.<wbr/></p>
-<p>If all regions have 0 weight,<wbr/> then no specific metering area
-needs to be used by the camera device.<wbr/> If the metering region is
-outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in capture result metadata,<wbr/>
-the camera device will ignore the sections outside the region and output the
-used sections in the result metadata.<wbr/></p>
+<p>The weights are relative to weights of other white balance metering regions,<wbr/> so if
+only one region is used,<wbr/> all non-zero weights will have the same effect.<wbr/> A region with
+0 weight is ignored.<wbr/></p>
+<p>If all regions have 0 weight,<wbr/> then no specific metering area needs to be used by the
+camera device.<wbr/></p>
+<p>If the metering region is outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in
+capture result metadata,<wbr/> the camera device will ignore the sections outside the crop
+region and output only the intersection rectangle as the metering region in the result
+metadata.<wbr/>  If the region is entirely outside the crop region,<wbr/> it will be ignored and
+not reported in the result metadata.<wbr/></p>
             </td>
           </tr>
 
@@ -3166,8 +3230,7 @@ use case.<wbr/></p></span>
 image while recording video) use case.<wbr/></p>
 <p>The camera device should take the highest-quality image
 possible (given the other settings) without disrupting the
-frame rate of video recording.<wbr/><br/>
-</p></span>
+frame rate of video recording.<wbr/>  </p></span>
                   </li>
                   <li>
                     <span class="entry_type_enum_name">ZERO_SHUTTER_LAG</span>
@@ -3198,7 +3261,6 @@ strategy.<wbr/></p>
             </td>
 
             <td class="entry_range">
-              <p>All must be supported except for ZERO_<wbr/>SHUTTER_<wbr/>LAG and MANUAL.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -3217,7 +3279,7 @@ strategy.<wbr/></p>
 <code><a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> != OFF</code> and any 3A routine is active.<wbr/></p>
 <p>ZERO_<wbr/>SHUTTER_<wbr/>LAG will be supported if <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a>
 contains ZSL.<wbr/> MANUAL will be supported if <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a>
-contains MANUAL_<wbr/>SENSOR.<wbr/></p>
+contains MANUAL_<wbr/>SENSOR.<wbr/> Other intent values are always supported.<wbr/></p>
             </td>
           </tr>
 
@@ -3329,8 +3391,6 @@ and implementation of these color effects is left to the
 implementor of the camera device,<wbr/> and should not be
 depended on to be consistent (or present) across all
 devices.<wbr/></p>
-<p>A color effect will only be applied if
-<a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> != OFF.<wbr/></p>
             </td>
           </tr>
 
@@ -3404,7 +3464,7 @@ discarded by the camera device.<wbr/></p></span>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Overall mode of 3A control
+              <p>Overall mode of 3A (auto-exposure,<wbr/> auto-white-balance,<wbr/> auto-focus) control
 routines.<wbr/></p>
             </td>
 
@@ -3412,7 +3472,6 @@ routines.<wbr/></p>
             </td>
 
             <td class="entry_range">
-              <p>all must be supported</p>
             </td>
 
             <td class="entry_tags">
@@ -3427,7 +3486,7 @@ routines.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>High-level 3A control.<wbr/> When set to OFF,<wbr/> all 3A control
+              <p>This is a top-level 3A control switch.<wbr/> When set to OFF,<wbr/> all 3A control
 by the camera device is disabled.<wbr/> The application must set the fields for
 capture parameters itself.<wbr/></p>
 <p>When set to AUTO,<wbr/> the individual algorithm controls in
@@ -3444,7 +3503,8 @@ where the application doesn't want a 3A manual control capture to affect
 the subsequent auto 3A capture results.<wbr/></p>
 <p>LEGACY mode devices will only support AUTO and USE_<wbr/>SCENE_<wbr/>MODE modes.<wbr/>
 LIMITED mode devices will only support OFF and OFF_<wbr/>KEEP_<wbr/>STATE if they
-support the MANUAL_<wbr/>SENSOR capability.<wbr/></p>
+support the MANUAL_<wbr/>SENSOR and MANUAL_<wbr/>POST_<wbr/>PROCSESING capabilities.<wbr/>
+FULL mode devices will always support OFF and OFF_<wbr/>KEEP_<wbr/>STATE.<wbr/></p>
             </td>
           </tr>
 
@@ -3645,8 +3705,7 @@ HAL3+ camera devices should not implement this mode.<wbr/></p></span>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>A camera mode optimized for conditions typical in a particular
-capture setting.<wbr/></p>
+              <p>Control for which scene mode is currently active.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -3668,12 +3727,12 @@ capture setting.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This is the mode that that is active when
+              <p>Scene modes are custom camera modes optimized for a certain set of conditions and
+capture settings.<wbr/></p>
+<p>This is the mode that that is active when
 <code><a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> == USE_<wbr/>SCENE_<wbr/>MODE</code>.<wbr/> Aside from FACE_<wbr/>PRIORITY,<wbr/>
 these modes will disable <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a>,<wbr/>
-<a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a>,<wbr/> and <a href="#controls_android.control.afMode">android.<wbr/>control.<wbr/>af<wbr/>Mode</a> while in use.<wbr/>
-The scene modes available for a given camera device are listed in
-<a href="#static_android.control.availableSceneModes">android.<wbr/>control.<wbr/>available<wbr/>Scene<wbr/>Modes</a>.<wbr/></p>
+<a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a>,<wbr/> and <a href="#controls_android.control.afMode">android.<wbr/>control.<wbr/>af<wbr/>Mode</a> while in use.<wbr/></p>
 <p>The interpretation and implementation of these scene modes is left
 to the implementor of the camera device.<wbr/> Their behavior will not be
 consistent across all devices,<wbr/> and any given device may only implement
@@ -3754,20 +3813,20 @@ active.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Video stabilization automatically translates and scales images from the camera
-in order to stabilize motion between consecutive frames.<wbr/></p>
+              <p>Video stabilization automatically translates and scales images from
+the camera in order to stabilize motion between consecutive frames.<wbr/></p>
 <p>If enabled,<wbr/> video stabilization can modify the
 <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> to keep the video stream stabilized.<wbr/></p>
-<p>Switching between different video stabilization modes may take several frames
-to initialize,<wbr/> the camera device will report the current mode in capture result
-metadata.<wbr/> For example,<wbr/> When "ON" mode is requested,<wbr/> the video stabilization modes
-in the first several capture results may still be "OFF",<wbr/> and it will become "ON"
-when the initialization is done.<wbr/></p>
-<p>If a camera device supports both this mode and OIS (<a href="#controls_android.lens.opticalStabilizationMode">android.<wbr/>lens.<wbr/>optical<wbr/>Stabilization<wbr/>Mode</a>),<wbr/>
-turning both modes on may produce undesirable interaction,<wbr/> so it is recommended not to
-enable both at the same time.<wbr/></p>
-<p>Some LEGACY camera devices will not support changing video stabilization
-mode; in this case the value will always override to OFF.<wbr/></p>
+<p>Switching between different video stabilization modes may take several
+frames to initialize,<wbr/> the camera device will report the current mode
+in capture result metadata.<wbr/> For example,<wbr/> When "ON" mode is requested,<wbr/>
+the video stabilization modes in the first several capture results may
+still be "OFF",<wbr/> and it will become "ON" when the initialization is
+done.<wbr/></p>
+<p>If a camera device supports both this mode and OIS
+(<a href="#controls_android.lens.opticalStabilizationMode">android.<wbr/>lens.<wbr/>optical<wbr/>Stabilization<wbr/>Mode</a>),<wbr/> turning both modes on may
+produce undesirable interaction,<wbr/> so it is recommended not to enable
+both at the same time.<wbr/></p>
             </td>
           </tr>
 
@@ -3827,7 +3886,7 @@ mode; in this case the value will always override to OFF.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The set of auto-exposure antibanding modes that are
+              <p>List of auto-exposure antibanding modes for <a href="#controls_android.control.aeAntibandingMode">android.<wbr/>control.<wbr/>ae<wbr/>Antibanding<wbr/>Mode</a> that are
 supported by this camera device.<wbr/></p>
             </td>
 
@@ -3835,6 +3894,7 @@ supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.control.aeAntibandingMode">android.<wbr/>control.<wbr/>ae<wbr/>Antibanding<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -3852,7 +3912,9 @@ supported by this camera device.<wbr/></p>
               <p>Not all of the auto-exposure anti-banding modes may be
 supported by a given camera device.<wbr/> This field lists the
 valid anti-banding modes that the application may request
-for this camera device; they must include AUTO.<wbr/></p>
+for this camera device with the
+<a href="#controls_android.control.aeAntibandingMode">android.<wbr/>control.<wbr/>ae<wbr/>Antibanding<wbr/>Mode</a> control.<wbr/> This list
+always includes AUTO.<wbr/></p>
             </td>
           </tr>
 
@@ -3885,14 +3947,15 @@ for this camera device; they must include AUTO.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The set of auto-exposure modes that are supported by this
-camera device.<wbr/></p>
+              <p>List of auto-exposure modes for <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> that are supported by this camera
+device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -3929,7 +3992,7 @@ capability.<wbr/></p>
                 
           <tr class="entry" id="static_android.control.aeAvailableTargetFpsRanges">
             <td class="entry_name
-             " rowspan="1">
+             " rowspan="3">
               android.<wbr/>control.<wbr/>ae<wbr/>Available<wbr/>Target<wbr/>Fps<wbr/>Ranges
             </td>
             <td class="entry_type">
@@ -3951,11 +4014,12 @@ capability.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of frame rate ranges supported by the
-auto-exposure (AE) algorithm/<wbr/>hardware</p>
+              <p>List of frame rate ranges for <a href="#controls_android.control.aeTargetFpsRange">android.<wbr/>control.<wbr/>ae<wbr/>Target<wbr/>Fps<wbr/>Range</a> supported by
+this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Frames per second (FPS)
             </td>
 
             <td class="entry_range">
@@ -3968,6 +4032,15 @@ auto-exposure (AE) algorithm/<wbr/>hardware</p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>For devices at the LIMITED level or above,<wbr/> this list will include at least (30,<wbr/> 30) for
+constant-framerate recording.<wbr/></p>
+            </td>
+          </tr>
 
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
@@ -3997,17 +4070,17 @@ auto-exposure (AE) algorithm/<wbr/>hardware</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Maximum and minimum exposure compensation
-setting,<wbr/> in counts of
-<a href="#static_android.control.aeCompensationStep">android.<wbr/>control.<wbr/>ae<wbr/>Compensation<wbr/>Step</a>.<wbr/></p>
+              <p>Maximum and minimum exposure compensation values for
+<a href="#controls_android.control.aeExposureCompensation">android.<wbr/>control.<wbr/>ae<wbr/>Exposure<wbr/>Compensation</a>,<wbr/> in counts of <a href="#static_android.control.aeCompensationStep">android.<wbr/>control.<wbr/>ae<wbr/>Compensation<wbr/>Step</a>,<wbr/>
+that are supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
-              <p>At least (-2,<wbr/>2)/<wbr/>(exp compensation step
-size)</p>
+              <p><code>Min.<wbr/>exposure compensation * <a href="#static_android.control.aeCompensationStep">android.<wbr/>control.<wbr/>ae<wbr/>Compensation<wbr/>Step</a> &lt;= -2 EV</code></p>
+<p><code>Max.<wbr/>exposure compensation * <a href="#static_android.control.aeCompensationStep">android.<wbr/>control.<wbr/>ae<wbr/>Compensation<wbr/>Step</a> &gt;= 2 EV</code></p>
             </td>
 
             <td class="entry_tags">
@@ -4025,7 +4098,7 @@ size)</p>
                 
           <tr class="entry" id="static_android.control.aeCompensationStep">
             <td class="entry_name
-             " rowspan="1">
+             " rowspan="5">
               android.<wbr/>control.<wbr/>ae<wbr/>Compensation<wbr/>Step
             </td>
             <td class="entry_type">
@@ -4042,15 +4115,15 @@ size)</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Smallest step by which exposure compensation
-can be changed</p>
+              <p>Smallest step by which the exposure compensation
+can be changed.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Exposure Value (EV)
             </td>
 
             <td class="entry_range">
-              <p>&lt;= 1/<wbr/>2</p>
             </td>
 
             <td class="entry_tags">
@@ -4060,7 +4133,27 @@ can be changed</p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>This is the unit for <a href="#controls_android.control.aeExposureCompensation">android.<wbr/>control.<wbr/>ae<wbr/>Exposure<wbr/>Compensation</a>.<wbr/> For example,<wbr/> if this key has
+a value of <code>1/<wbr/>2</code>,<wbr/> then a setting of <code>-2</code> for <a href="#controls_android.control.aeExposureCompensation">android.<wbr/>control.<wbr/>ae<wbr/>Exposure<wbr/>Compensation</a> means
+that the target EV offset for the auto-exposure routine is -1 EV.<wbr/></p>
+<p>One unit of EV compensation changes the brightness of the captured image by a factor
+of two.<wbr/> +1 EV doubles the image brightness,<wbr/> while -1 EV halves the image brightness.<wbr/></p>
+            </td>
+          </tr>
 
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">HAL Implementation Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>This must be less than or equal to 1/<wbr/>2.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
            <!-- end of entry -->
@@ -4090,14 +4183,15 @@ can be changed</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of auto-focus (AF) modes that can be
-selected with <a href="#controls_android.control.afMode">android.<wbr/>control.<wbr/>af<wbr/>Mode</a>.<wbr/></p>
+              <p>List of auto-focus (AF) modes for <a href="#controls_android.control.afMode">android.<wbr/>control.<wbr/>af<wbr/>Mode</a> that are
+supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.control.afMode">android.<wbr/>control.<wbr/>af<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -4153,17 +4247,15 @@ focusing to infinity (by also setting <a href="#controls_android.lens.focusDista
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List containing the subset of color effects
-specified in <a href="#controls_android.control.effectMode">android.<wbr/>control.<wbr/>effect<wbr/>Mode</a> that is supported by
-this device.<wbr/></p>
+              <p>List of color effects for <a href="#controls_android.control.effectMode">android.<wbr/>control.<wbr/>effect<wbr/>Mode</a> that are supported by this camera
+device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
-              <p>Any subset of enums from those specified in
-<a href="#controls_android.control.effectMode">android.<wbr/>control.<wbr/>effect<wbr/>Mode</a>.<wbr/>  OFF must be included in any subset.<wbr/></p>
+              <p>Any value listed in <a href="#controls_android.control.effectMode">android.<wbr/>control.<wbr/>effect<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -4179,13 +4271,14 @@ this device.<wbr/></p>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
               <p>This list contains the color effect modes that can be applied to
-images produced by the camera device.<wbr/> Only modes that have
-been fully implemented for the current device may be included here.<wbr/>
+images produced by the camera device.<wbr/>
 Implementations are not expected to be consistent across all devices.<wbr/>
-If no color effect modes are available for a device,<wbr/> this should
-simply be set to OFF.<wbr/></p>
+If no color effect modes are available for a device,<wbr/> this will only list
+OFF.<wbr/></p>
 <p>A color effect will only be applied if
-<a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> != OFF.<wbr/></p>
+<a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> != OFF.<wbr/>  OFF is always included in this list.<wbr/></p>
+<p>This control has no effect on the operation of other control routines such
+as auto-exposure,<wbr/> white balance,<wbr/> or focus.<wbr/></p>
             </td>
           </tr>
 
@@ -4218,18 +4311,15 @@ simply be set to OFF.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List containing a subset of scene modes
-specified in <a href="#controls_android.control.sceneMode">android.<wbr/>control.<wbr/>scene<wbr/>Mode</a>.<wbr/></p>
+              <p>List of scene modes for <a href="#controls_android.control.sceneMode">android.<wbr/>control.<wbr/>scene<wbr/>Mode</a> that are supported by this camera
+device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
-              <p>Any subset of the enums specified in <a href="#controls_android.control.sceneMode">android.<wbr/>control.<wbr/>scene<wbr/>Mode</a>
-not including DISABLED,<wbr/> or solely DISABLED if no
-scene modes are available.<wbr/> FACE_<wbr/>PRIORITY must be included
-if face detection is supported (i.<wbr/>e.<wbr/><code><a href="#static_android.statistics.info.maxFaceCount">android.<wbr/>statistics.<wbr/>info.<wbr/>max<wbr/>Face<wbr/>Count</a> &gt; 0</code>).<wbr/></p>
+              <p>Any value listed in <a href="#controls_android.control.sceneMode">android.<wbr/>control.<wbr/>scene<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -4247,8 +4337,12 @@ if face detection is supported (i.<wbr/>e.<wbr/><code><a href="#static_android.s
               <p>This list contains scene modes that can be set for the camera device.<wbr/>
 Only scene modes that have been fully implemented for the
 camera device may be included here.<wbr/> Implementations are not expected
-to be consistent across all devices.<wbr/> If no scene modes are supported
-by the camera device,<wbr/> this will be set to <code>[DISABLED]</code>.<wbr/></p>
+to be consistent across all devices.<wbr/></p>
+<p>If no scene modes are supported by the camera device,<wbr/> this
+will be set to DISABLED.<wbr/> Otherwise DISABLED will not be listed.<wbr/></p>
+<p>FACE_<wbr/>PRIORITY is always listed if face detection is
+supported (i.<wbr/>e.<wbr/><code><a href="#static_android.statistics.info.maxFaceCount">android.<wbr/>statistics.<wbr/>info.<wbr/>max<wbr/>Face<wbr/>Count</a> &gt;
+0</code>).<wbr/></p>
             </td>
           </tr>
 
@@ -4259,7 +4353,7 @@ by the camera device,<wbr/> this will be set to <code>[DISABLED]</code>.<wbr/></
                 
           <tr class="entry" id="static_android.control.availableVideoStabilizationModes">
             <td class="entry_name
-             " rowspan="1">
+             " rowspan="3">
               android.<wbr/>control.<wbr/>available<wbr/>Video<wbr/>Stabilization<wbr/>Modes
             </td>
             <td class="entry_type">
@@ -4281,15 +4375,15 @@ by the camera device,<wbr/> this will be set to <code>[DISABLED]</code>.<wbr/></
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of video stabilization modes that can
-be supported</p>
+              <p>List of video stabilization modes for <a href="#controls_android.control.videoStabilizationMode">android.<wbr/>control.<wbr/>video<wbr/>Stabilization<wbr/>Mode</a>
+that are supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
-              <p>OFF must be included</p>
+              <p>Any value listed in <a href="#controls_android.control.videoStabilizationMode">android.<wbr/>control.<wbr/>video<wbr/>Stabilization<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -4299,6 +4393,14 @@ be supported</p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>OFF will always be listed.<wbr/></p>
+            </td>
+          </tr>
 
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
@@ -4329,14 +4431,15 @@ be supported</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The set of auto-white-balance modes (<a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a>)
-that are supported by this camera device.<wbr/></p>
+              <p>List of auto-white-balance modes for <a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a> that are supported by this
+camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -4355,9 +4458,10 @@ that are supported by this camera device.<wbr/></p>
 given camera device.<wbr/> This entry lists the valid modes for
 <a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a> for this camera device.<wbr/></p>
 <p>All camera devices will support ON mode.<wbr/></p>
-<p>FULL mode camera devices will always support OFF mode,<wbr/>
-which enables application control of white balance,<wbr/> by using
-<a href="#controls_android.colorCorrection.transform">android.<wbr/>color<wbr/>Correction.<wbr/>transform</a> and <a href="#controls_android.colorCorrection.gains">android.<wbr/>color<wbr/>Correction.<wbr/>gains</a>(<a href="#controls_android.colorCorrection.mode">android.<wbr/>color<wbr/>Correction.<wbr/>mode</a> must be set to TRANSFORM_<wbr/>MATRIX).<wbr/></p>
+<p>Camera devices that support the MANUAL_<wbr/>POST_<wbr/>PROCESSING capability will always support OFF
+mode,<wbr/> which enables application control of white balance,<wbr/> by using
+<a href="#controls_android.colorCorrection.transform">android.<wbr/>color<wbr/>Correction.<wbr/>transform</a> and <a href="#controls_android.colorCorrection.gains">android.<wbr/>color<wbr/>Correction.<wbr/>gains</a>(<a href="#controls_android.colorCorrection.mode">android.<wbr/>color<wbr/>Correction.<wbr/>mode</a> must be set to TRANSFORM_<wbr/>MATRIX).<wbr/> This includes all FULL
+mode camera devices.<wbr/></p>
             </td>
           </tr>
 
@@ -4420,7 +4524,7 @@ this value must be &gt;= 1 for AE and AF.<wbr/> The order of the elements is:
                 
           <tr class="entry" id="static_android.control.maxRegionsAe">
             <td class="entry_name
-             " rowspan="3">
+             " rowspan="5">
               android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae
             </td>
             <td class="entry_type">
@@ -4438,10 +4542,8 @@ this value must be &gt;= 1 for AE and AF.<wbr/> The order of the elements is:
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of the maximum number of regions that can be used for metering in
-auto-exposure (AE);
-this corresponds to the the maximum number of elements in
-<a href="#controls_android.control.aeRegions">android.<wbr/>control.<wbr/>ae<wbr/>Regions</a>.<wbr/></p>
+              <p>The maximum number of metering regions that can be used by the auto-exposure (AE)
+routine.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -4456,6 +4558,15 @@ value will be &gt;= 1.<wbr/></p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>This corresponds to the the maximum allowed number of elements in
+<a href="#controls_android.control.aeRegions">android.<wbr/>control.<wbr/>ae<wbr/>Regions</a>.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entries_header">
             <th class="th_details" colspan="5">HAL Implementation Details</th>
@@ -4473,7 +4584,7 @@ maxRegions to have this entry be automatically populated.<wbr/></p>
                 
           <tr class="entry" id="static_android.control.maxRegionsAwb">
             <td class="entry_name
-             " rowspan="3">
+             " rowspan="5">
               android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Awb
             </td>
             <td class="entry_type">
@@ -4491,10 +4602,8 @@ maxRegions to have this entry be automatically populated.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of the maximum number of regions that can be used for metering in
-auto-white balance (AWB);
-this corresponds to the the maximum number of elements in
-<a href="#controls_android.control.awbRegions">android.<wbr/>control.<wbr/>awb<wbr/>Regions</a>.<wbr/></p>
+              <p>The maximum number of metering regions that can be used by the auto-white balance (AWB)
+routine.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -4508,6 +4617,15 @@ this corresponds to the the maximum number of elements in
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>This corresponds to the the maximum allowed number of elements in
+<a href="#controls_android.control.awbRegions">android.<wbr/>control.<wbr/>awb<wbr/>Regions</a>.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entries_header">
             <th class="th_details" colspan="5">HAL Implementation Details</th>
@@ -4525,7 +4643,7 @@ maxRegions to have this entry be automatically populated.<wbr/></p>
                 
           <tr class="entry" id="static_android.control.maxRegionsAf">
             <td class="entry_name
-             " rowspan="3">
+             " rowspan="5">
               android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Af
             </td>
             <td class="entry_type">
@@ -4543,10 +4661,7 @@ maxRegions to have this entry be automatically populated.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of the maximum number of regions that can be used for metering in
-auto-focus (AF);
-this corresponds to the the maximum number of elements in
-<a href="#controls_android.control.afRegions">android.<wbr/>control.<wbr/>af<wbr/>Regions</a>.<wbr/></p>
+              <p>The maximum number of metering regions that can be used by the auto-focus (AF) routine.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -4561,6 +4676,15 @@ value will be &gt;= 1.<wbr/></p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>This corresponds to the the maximum allowed number of elements in
+<a href="#controls_android.control.afRegions">android.<wbr/>control.<wbr/>af<wbr/>Regions</a>.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entries_header">
             <th class="th_details" colspan="5">HAL Implementation Details</th>
@@ -4915,7 +5039,7 @@ control.<wbr/></p>
 options for the antibanding mode.<wbr/> The
 <a href="#static_android.control.aeAvailableAntibandingModes">android.<wbr/>control.<wbr/>ae<wbr/>Available<wbr/>Antibanding<wbr/>Modes</a> key contains
 the available modes for a given camera device.<wbr/></p>
-<p>The default mode is AUTO,<wbr/> which must be supported by all
+<p>The default mode is AUTO,<wbr/> which is supported by all
 camera devices.<wbr/></p>
 <p>If manual exposure control is enabled (by setting
 <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> or <a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> to OFF),<wbr/>
@@ -4969,7 +5093,7 @@ brightness.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              count of positive/<wbr/>negative EV steps
+              Compensation steps
             </td>
 
             <td class="entry_range">
@@ -5069,9 +5193,11 @@ calculated values.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Note that even when AE is locked,<wbr/> the flash may be
-fired if the <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> is ON_<wbr/>AUTO_<wbr/>FLASH /<wbr/> ON_<wbr/>ALWAYS_<wbr/>FLASH /<wbr/>
-ON_<wbr/>AUTO_<wbr/>FLASH_<wbr/>REDEYE.<wbr/></p>
+              <p>When set to <code>true</code> (ON),<wbr/> the AE algorithm is locked to its latest parameters,<wbr/>
+and will not change exposure settings until the lock is set to <code>false</code> (OFF).<wbr/></p>
+<p>Note that even when AE is locked,<wbr/> the flash may be fired if
+the <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> is ON_<wbr/>AUTO_<wbr/>FLASH /<wbr/>
+ON_<wbr/>ALWAYS_<wbr/>FLASH /<wbr/> ON_<wbr/>AUTO_<wbr/>FLASH_<wbr/>REDEYE.<wbr/></p>
 <p>When <a href="#controls_android.control.aeExposureCompensation">android.<wbr/>control.<wbr/>ae<wbr/>Exposure<wbr/>Compensation</a> is changed,<wbr/> even if the AE lock
 is ON,<wbr/> the camera device will still adjust its exposure value.<wbr/></p>
 <p>If AE precapture is triggered (see <a href="#controls_android.control.aePrecaptureTrigger">android.<wbr/>control.<wbr/>ae<wbr/>Precapture<wbr/>Trigger</a>)
@@ -5080,6 +5206,19 @@ when AE is already locked,<wbr/> the camera device will not change the exposure
 parameters.<wbr/> The flash may be fired if the <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a>
 is ON_<wbr/>AUTO_<wbr/>FLASH/<wbr/>ON_<wbr/>AUTO_<wbr/>FLASH_<wbr/>REDEYE and the scene is too dark.<wbr/> If the
 <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> is ON_<wbr/>ALWAYS_<wbr/>FLASH,<wbr/> the scene may become overexposed.<wbr/></p>
+<p>Since the camera device has a pipeline of in-flight requests,<wbr/> the settings that
+get locked do not necessarily correspond to the settings that were present in the
+latest capture result received from the camera device,<wbr/> since additional captures
+and AE updates may have occurred even before the result was sent out.<wbr/> If an
+application is switching between automatic and manual control and wishes to eliminate
+any flicker during the switch,<wbr/> the following procedure is recommended:</p>
+<ol>
+<li>Starting in auto-AE mode:</li>
+<li>Lock AE</li>
+<li>Wait for the first result to be output that has the AE locked</li>
+<li>Copy exposure settings from that result into a request,<wbr/> set the request to manual AE</li>
+<li>Submit the capture request,<wbr/> proceed to run manual AE as desired.<wbr/></li>
+</ol>
 <p>See <a href="#dynamic_android.control.aeState">android.<wbr/>control.<wbr/>ae<wbr/>State</a> for AE lock related state transition details.<wbr/></p>
             </td>
           </tr>
@@ -5233,15 +5372,16 @@ CaptureResult.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of areas to use for
-metering.<wbr/></p>
+              <p>List of metering areas to use for auto-exposure adjustment.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
             </td>
 
             <td class="entry_range">
-              <p><code>area_<wbr/>count &lt;= <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a></code></p>
+              <p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
             </td>
 
             <td class="entry_tags">
@@ -5256,23 +5396,30 @@ metering.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Optional.<wbr/> Not available if <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a> is 0.<wbr/>
+              <p>Not available if <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a> is 0.<wbr/>
 Otherwise will always be present.<wbr/></p>
+<p>The maximum number of regions supported by the device is determined by the value
+of <a href="#static_android.control.maxRegionsAe">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Ae</a>.<wbr/></p>
 <p>The coordinate system is based on the active pixel array,<wbr/>
 with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
 (<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
 <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
 bottom-right pixel in the active pixel array.<wbr/></p>
-<p>The weight must range from 0 to 1000,<wbr/> and represents a weight
+<p>The weight must be within <code>[0,<wbr/> 1000]</code>,<wbr/> and represents a weight
 for every pixel in the area.<wbr/> This means that a large metering area
 with the same weight as a smaller area will have more effect in
 the metering result.<wbr/> Metering areas can partially overlap and the
 camera device will add the weights in the overlap region.<wbr/></p>
-<p>If all regions have 0 weight,<wbr/> then no specific metering area
-needs to be used by the camera device.<wbr/> If the metering region is
-outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in capture result metadata,<wbr/>
-the camera device will ignore the sections outside the region and output the
-used sections in the result metadata.<wbr/></p>
+<p>The weights are relative to weights of other exposure metering regions,<wbr/> so if only one
+region is used,<wbr/> all non-zero weights will have the same effect.<wbr/> A region with 0
+weight is ignored.<wbr/></p>
+<p>If all regions have 0 weight,<wbr/> then no specific metering area needs to be used by the
+camera device.<wbr/></p>
+<p>If the metering region is outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in
+capture result metadata,<wbr/> the camera device will ignore the sections outside the crop
+region and output only the intersection rectangle as the metering region in the result
+metadata.<wbr/>  If the region is entirely outside the crop region,<wbr/> it will be ignored and
+not reported in the result metadata.<wbr/></p>
             </td>
           </tr>
 
@@ -5317,15 +5464,17 @@ exclusive on xmax and ymax.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Range over which fps can be adjusted to
-maintain exposure.<wbr/></p>
+              <p>Range over which the auto-exposure routine can
+adjust the capture frame rate to maintain good
+exposure.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Frames per second (FPS)
             </td>
 
             <td class="entry_range">
-              <p><a href="#static_android.control.aeAvailableTargetFpsRanges">android.<wbr/>control.<wbr/>ae<wbr/>Available<wbr/>Target<wbr/>Fps<wbr/>Ranges</a></p>
+              <p>Any of the entries in <a href="#static_android.control.aeAvailableTargetFpsRanges">android.<wbr/>control.<wbr/>ae<wbr/>Available<wbr/>Target<wbr/>Fps<wbr/>Ranges</a></p>
             </td>
 
             <td class="entry_tags">
@@ -5341,7 +5490,8 @@ maintain exposure.<wbr/></p>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
               <p>Only constrains auto-exposure (AE) algorithm,<wbr/> not
-manual control of <a href="#controls_android.sensor.exposureTime">android.<wbr/>sensor.<wbr/>exposure<wbr/>Time</a></p>
+manual control of <a href="#controls_android.sensor.exposureTime">android.<wbr/>sensor.<wbr/>exposure<wbr/>Time</a> and
+<a href="#controls_android.sensor.frameDuration">android.<wbr/>sensor.<wbr/>frame<wbr/>Duration</a>.<wbr/></p>
             </td>
           </tr>
 
@@ -5420,6 +5570,10 @@ sequence completes before starting a new one.<wbr/></p>
 depends on the current AE mode and state; see
 <a href="#dynamic_android.control.aeState">android.<wbr/>control.<wbr/>ae<wbr/>State</a> for AE precapture state transition
 details.<wbr/></p>
+<p>On LEGACY-level devices,<wbr/> the precapture trigger is not supported;
+capturing a high-resolution JPEG image will automatically trigger a
+precapture sequence before the high-resolution capture,<wbr/> including
+potentially firing a pre-capture flash.<wbr/></p>
             </td>
           </tr>
 
@@ -5883,15 +6037,16 @@ that will arise on camera modules with open-loop VCMs.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of areas to use for focus
-estimation.<wbr/></p>
+              <p>List of metering areas to use for auto-focus.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
             </td>
 
             <td class="entry_range">
-              <p><code>area_<wbr/>count &lt;= <a href="#static_android.control.maxRegions">android.<wbr/>control.<wbr/>max<wbr/>Regions</a>[2]</code></p>
+              <p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
             </td>
 
             <td class="entry_tags">
@@ -5906,23 +6061,30 @@ estimation.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Optional.<wbr/> Not available if <a href="#static_android.control.maxRegionsAf">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Af</a> is 0.<wbr/>
+              <p>Not available if <a href="#static_android.control.maxRegionsAf">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Af</a> is 0.<wbr/>
 Otherwise will always be present.<wbr/></p>
+<p>The maximum number of focus areas supported by the device is determined by the value
+of <a href="#static_android.control.maxRegionsAf">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Af</a>.<wbr/></p>
 <p>The coordinate system is based on the active pixel array,<wbr/>
 with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
 (<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
 <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>height - 1) being the
 bottom-right pixel in the active pixel array.<wbr/></p>
-<p>The weight must range from 0 to 1000,<wbr/> and represents a weight
+<p>The weight must be within <code>[0,<wbr/> 1000]</code>,<wbr/> and represents a weight
 for every pixel in the area.<wbr/> This means that a large metering area
 with the same weight as a smaller area will have more effect in
 the metering result.<wbr/> Metering areas can partially overlap and the
 camera device will add the weights in the overlap region.<wbr/></p>
-<p>If all regions have 0 weight,<wbr/> then no specific metering area
-needs to be used by the camera device.<wbr/> If the metering region is
-outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in capture result metadata,<wbr/>
-the camera device will ignore the sections outside the region and output the
-used sections in the result metadata.<wbr/></p>
+<p>The weights are relative to weights of other metering regions,<wbr/> so if only one region
+is used,<wbr/> all non-zero weights will have the same effect.<wbr/> A region with 0 weight is
+ignored.<wbr/></p>
+<p>If all regions have 0 weight,<wbr/> then no specific metering area needs to be used by the
+camera device.<wbr/></p>
+<p>If the metering region is outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in
+capture result metadata,<wbr/> the camera device will ignore the sections outside the crop
+region and output only the intersection rectangle as the metering region in the result
+metadata.<wbr/> If the region is entirely outside the crop region,<wbr/> it will be ignored and
+not reported in the result metadata.<wbr/></p>
             </td>
           </tr>
 
@@ -6611,7 +6773,22 @@ latest calculated values.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Note that AWB lock is only meaningful when
+              <p>When set to <code>true</code> (ON),<wbr/> the AWB algorithm is locked to its latest parameters,<wbr/>
+and will not change color balance settings until the lock is set to <code>false</code> (OFF).<wbr/></p>
+<p>Since the camera device has a pipeline of in-flight requests,<wbr/> the settings that
+get locked do not necessarily correspond to the settings that were present in the
+latest capture result received from the camera device,<wbr/> since additional captures
+and AWB updates may have occurred even before the result was sent out.<wbr/> If an
+application is switching between automatic and manual control and wishes to eliminate
+any flicker during the switch,<wbr/> the following procedure is recommended:</p>
+<ol>
+<li>Starting in auto-AWB mode:</li>
+<li>Lock AWB</li>
+<li>Wait for the first result to be output that has the AWB locked</li>
+<li>Copy AWB settings from that result into a request,<wbr/> set the request to manual AWB</li>
+<li>Submit the capture request,<wbr/> proceed to run manual AWB as desired.<wbr/></li>
+</ol>
+<p>Note that AWB lock is only meaningful when
 <a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a> is in the AUTO mode; in other modes,<wbr/>
 AWB is already fixed to a specific setting.<wbr/></p>
 <p>Some LEGACY devices may not support ON; the value is then overridden to OFF.<wbr/></p>
@@ -6820,15 +6997,17 @@ adjustment.<wbr/> The application's values for
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of areas to use for illuminant
+              <p>List of metering areas to use for auto-white-balance illuminant
 estimation.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Pixel coordinates within android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
             </td>
 
             <td class="entry_range">
-              <p><code>area_<wbr/>count &lt;= <a href="#static_android.control.maxRegions">android.<wbr/>control.<wbr/>max<wbr/>Regions</a>[1]</code></p>
+              <p>Coordinates must be between <code>[(0,<wbr/>0),<wbr/> (width,<wbr/> height))</code> of
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a></p>
             </td>
 
             <td class="entry_tags">
@@ -6843,8 +7022,10 @@ estimation.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Optional.<wbr/> Not available if <a href="#static_android.control.maxRegionsAwb">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Awb</a> is 0.<wbr/>
+              <p>Not available if <a href="#static_android.control.maxRegionsAwb">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Awb</a> is 0.<wbr/>
 Otherwise will always be present.<wbr/></p>
+<p>The maximum number of regions supported by the device is determined by the value
+of <a href="#static_android.control.maxRegionsAwb">android.<wbr/>control.<wbr/>max<wbr/>Regions<wbr/>Awb</a>.<wbr/></p>
 <p>The coordinate system is based on the active pixel array,<wbr/>
 with (0,<wbr/>0) being the top-left pixel in the active pixel array,<wbr/> and
 (<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/>width - 1,<wbr/>
@@ -6855,11 +7036,16 @@ for every pixel in the area.<wbr/> This means that a large metering area
 with the same weight as a smaller area will have more effect in
 the metering result.<wbr/> Metering areas can partially overlap and the
 camera device will add the weights in the overlap region.<wbr/></p>
-<p>If all regions have 0 weight,<wbr/> then no specific metering area
-needs to be used by the camera device.<wbr/> If the metering region is
-outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in capture result metadata,<wbr/>
-the camera device will ignore the sections outside the region and output the
-used sections in the result metadata.<wbr/></p>
+<p>The weights are relative to weights of other white balance metering regions,<wbr/> so if
+only one region is used,<wbr/> all non-zero weights will have the same effect.<wbr/> A region with
+0 weight is ignored.<wbr/></p>
+<p>If all regions have 0 weight,<wbr/> then no specific metering area needs to be used by the
+camera device.<wbr/></p>
+<p>If the metering region is outside the used <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> returned in
+capture result metadata,<wbr/> the camera device will ignore the sections outside the crop
+region and output only the intersection rectangle as the metering region in the result
+metadata.<wbr/>  If the region is entirely outside the crop region,<wbr/> it will be ignored and
+not reported in the result metadata.<wbr/></p>
             </td>
           </tr>
 
@@ -6926,8 +7112,7 @@ use case.<wbr/></p></span>
 image while recording video) use case.<wbr/></p>
 <p>The camera device should take the highest-quality image
 possible (given the other settings) without disrupting the
-frame rate of video recording.<wbr/><br/>
-</p></span>
+frame rate of video recording.<wbr/>  </p></span>
                   </li>
                   <li>
                     <span class="entry_type_enum_name">ZERO_SHUTTER_LAG</span>
@@ -6958,7 +7143,6 @@ strategy.<wbr/></p>
             </td>
 
             <td class="entry_range">
-              <p>All must be supported except for ZERO_<wbr/>SHUTTER_<wbr/>LAG and MANUAL.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -6977,7 +7161,7 @@ strategy.<wbr/></p>
 <code><a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> != OFF</code> and any 3A routine is active.<wbr/></p>
 <p>ZERO_<wbr/>SHUTTER_<wbr/>LAG will be supported if <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a>
 contains ZSL.<wbr/> MANUAL will be supported if <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a>
-contains MANUAL_<wbr/>SENSOR.<wbr/></p>
+contains MANUAL_<wbr/>SENSOR.<wbr/> Other intent values are always supported.<wbr/></p>
             </td>
           </tr>
 
@@ -7275,8 +7459,6 @@ and implementation of these color effects is left to the
 implementor of the camera device,<wbr/> and should not be
 depended on to be consistent (or present) across all
 devices.<wbr/></p>
-<p>A color effect will only be applied if
-<a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> != OFF.<wbr/></p>
             </td>
           </tr>
 
@@ -7350,7 +7532,7 @@ discarded by the camera device.<wbr/></p></span>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Overall mode of 3A control
+              <p>Overall mode of 3A (auto-exposure,<wbr/> auto-white-balance,<wbr/> auto-focus) control
 routines.<wbr/></p>
             </td>
 
@@ -7358,7 +7540,6 @@ routines.<wbr/></p>
             </td>
 
             <td class="entry_range">
-              <p>all must be supported</p>
             </td>
 
             <td class="entry_tags">
@@ -7373,7 +7554,7 @@ routines.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>High-level 3A control.<wbr/> When set to OFF,<wbr/> all 3A control
+              <p>This is a top-level 3A control switch.<wbr/> When set to OFF,<wbr/> all 3A control
 by the camera device is disabled.<wbr/> The application must set the fields for
 capture parameters itself.<wbr/></p>
 <p>When set to AUTO,<wbr/> the individual algorithm controls in
@@ -7390,7 +7571,8 @@ where the application doesn't want a 3A manual control capture to affect
 the subsequent auto 3A capture results.<wbr/></p>
 <p>LEGACY mode devices will only support AUTO and USE_<wbr/>SCENE_<wbr/>MODE modes.<wbr/>
 LIMITED mode devices will only support OFF and OFF_<wbr/>KEEP_<wbr/>STATE if they
-support the MANUAL_<wbr/>SENSOR capability.<wbr/></p>
+support the MANUAL_<wbr/>SENSOR and MANUAL_<wbr/>POST_<wbr/>PROCSESING capabilities.<wbr/>
+FULL mode devices will always support OFF and OFF_<wbr/>KEEP_<wbr/>STATE.<wbr/></p>
             </td>
           </tr>
 
@@ -7591,8 +7773,7 @@ HAL3+ camera devices should not implement this mode.<wbr/></p></span>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>A camera mode optimized for conditions typical in a particular
-capture setting.<wbr/></p>
+              <p>Control for which scene mode is currently active.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -7614,12 +7795,12 @@ capture setting.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This is the mode that that is active when
+              <p>Scene modes are custom camera modes optimized for a certain set of conditions and
+capture settings.<wbr/></p>
+<p>This is the mode that that is active when
 <code><a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> == USE_<wbr/>SCENE_<wbr/>MODE</code>.<wbr/> Aside from FACE_<wbr/>PRIORITY,<wbr/>
 these modes will disable <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a>,<wbr/>
-<a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a>,<wbr/> and <a href="#controls_android.control.afMode">android.<wbr/>control.<wbr/>af<wbr/>Mode</a> while in use.<wbr/>
-The scene modes available for a given camera device are listed in
-<a href="#static_android.control.availableSceneModes">android.<wbr/>control.<wbr/>available<wbr/>Scene<wbr/>Modes</a>.<wbr/></p>
+<a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a>,<wbr/> and <a href="#controls_android.control.afMode">android.<wbr/>control.<wbr/>af<wbr/>Mode</a> while in use.<wbr/></p>
 <p>The interpretation and implementation of these scene modes is left
 to the implementor of the camera device.<wbr/> Their behavior will not be
 consistent across all devices,<wbr/> and any given device may only implement
@@ -7700,20 +7881,20 @@ active.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Video stabilization automatically translates and scales images from the camera
-in order to stabilize motion between consecutive frames.<wbr/></p>
+              <p>Video stabilization automatically translates and scales images from
+the camera in order to stabilize motion between consecutive frames.<wbr/></p>
 <p>If enabled,<wbr/> video stabilization can modify the
 <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> to keep the video stream stabilized.<wbr/></p>
-<p>Switching between different video stabilization modes may take several frames
-to initialize,<wbr/> the camera device will report the current mode in capture result
-metadata.<wbr/> For example,<wbr/> When "ON" mode is requested,<wbr/> the video stabilization modes
-in the first several capture results may still be "OFF",<wbr/> and it will become "ON"
-when the initialization is done.<wbr/></p>
-<p>If a camera device supports both this mode and OIS (<a href="#controls_android.lens.opticalStabilizationMode">android.<wbr/>lens.<wbr/>optical<wbr/>Stabilization<wbr/>Mode</a>),<wbr/>
-turning both modes on may produce undesirable interaction,<wbr/> so it is recommended not to
-enable both at the same time.<wbr/></p>
-<p>Some LEGACY camera devices will not support changing video stabilization
-mode; in this case the value will always override to OFF.<wbr/></p>
+<p>Switching between different video stabilization modes may take several
+frames to initialize,<wbr/> the camera device will report the current mode
+in capture result metadata.<wbr/> For example,<wbr/> When "ON" mode is requested,<wbr/>
+the video stabilization modes in the first several capture results may
+still be "OFF",<wbr/> and it will become "ON" when the initialization is
+done.<wbr/></p>
+<p>If a camera device supports both this mode and OIS
+(<a href="#controls_android.lens.opticalStabilizationMode">android.<wbr/>lens.<wbr/>optical<wbr/>Stabilization<wbr/>Mode</a>),<wbr/> turning both modes on may
+produce undesirable interaction,<wbr/> so it is recommended not to enable
+both at the same time.<wbr/></p>
             </td>
           </tr>
 
@@ -7881,6 +8062,7 @@ enhancement.<wbr/></p>
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.edge.availableEdgeModes">android.<wbr/>edge.<wbr/>available<wbr/>Edge<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -7895,9 +8077,8 @@ enhancement.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Edge/<wbr/>sharpness/<wbr/>detail enhancement.<wbr/> OFF means no
-enhancement will be applied by the camera device.<wbr/></p>
-<p>This must be set to one of the modes listed in <a href="#static_android.edge.availableEdgeModes">android.<wbr/>edge.<wbr/>available<wbr/>Edge<wbr/>Modes</a>.<wbr/></p>
+              <p>Edge enhancement improves sharpness and details in the captured image.<wbr/> OFF means
+no enhancement will be applied by the camera device.<wbr/></p>
 <p>FAST/<wbr/>HIGH_<wbr/>QUALITY both mean camera device determined enhancement
 will be applied.<wbr/> HIGH_<wbr/>QUALITY mode indicates that the
 camera device will use the highest-quality enhancement algorithms,<wbr/>
@@ -8004,13 +8185,15 @@ applied to the images</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The set of edge enhancement modes supported by this camera device.<wbr/></p>
+              <p>List of edge enhancement modes for <a href="#controls_android.edge.mode">android.<wbr/>edge.<wbr/>mode</a> that are supported by this camera
+device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.edge.mode">android.<wbr/>edge.<wbr/>mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -8025,8 +8208,7 @@ applied to the images</p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This tag lists the valid modes for <a href="#controls_android.edge.mode">android.<wbr/>edge.<wbr/>mode</a>.<wbr/></p>
-<p>Full-capability camera devices must always support OFF and FAST.<wbr/></p>
+              <p>Full-capability camera devices must always support OFF; all devices will list FAST.<wbr/></p>
             </td>
           </tr>
 
@@ -8104,6 +8286,7 @@ enhancement.<wbr/></p>
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.edge.availableEdgeModes">android.<wbr/>edge.<wbr/>available<wbr/>Edge<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -8118,9 +8301,8 @@ enhancement.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Edge/<wbr/>sharpness/<wbr/>detail enhancement.<wbr/> OFF means no
-enhancement will be applied by the camera device.<wbr/></p>
-<p>This must be set to one of the modes listed in <a href="#static_android.edge.availableEdgeModes">android.<wbr/>edge.<wbr/>available<wbr/>Edge<wbr/>Modes</a>.<wbr/></p>
+              <p>Edge enhancement improves sharpness and details in the captured image.<wbr/> OFF means
+no enhancement will be applied by the camera device.<wbr/></p>
 <p>FAST/<wbr/>HIGH_<wbr/>QUALITY both mean camera device determined enhancement
 will be applied.<wbr/> HIGH_<wbr/>QUALITY mode indicates that the
 camera device will use the highest-quality enhancement algorithms,<wbr/>
@@ -8403,7 +8585,7 @@ for use cases such as preview,<wbr/> auto-focus assist,<wbr/> still capture,<wbr
 
             <td class="entry_description">
               <p>Whether this camera device has a
-flash.<wbr/></p>
+flash unit.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -8424,8 +8606,9 @@ flash.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If no flash,<wbr/> none of the flash controls do
-anything.<wbr/> All other metadata should return 0.<wbr/></p>
+              <p>Will be <code>false</code> if no flash is available.<wbr/></p>
+<p>If there is no flash unit,<wbr/> none of the flash controls do
+anything.<wbr/></p>
             </td>
           </tr>
 
@@ -8937,13 +9120,14 @@ of reducing frame rate relative to sensor raw output.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Set operational mode for hot pixel correction.<wbr/></p>
+              <p>Operational mode for hot pixel correction.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.hotPixel.availableHotPixelModes">android.<wbr/>hot<wbr/>Pixel.<wbr/>available<wbr/>Hot<wbr/>Pixel<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -8959,11 +9143,9 @@ of reducing frame rate relative to sensor raw output.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Valid modes for this camera device are listed in
-<a href="#static_android.hotPixel.availableHotPixelModes">android.<wbr/>hot<wbr/>Pixel.<wbr/>available<wbr/>Hot<wbr/>Pixel<wbr/>Modes</a>.<wbr/></p>
-<p>Hotpixel correction interpolates out,<wbr/> or otherwise removes,<wbr/> pixels
-that do not accurately encode the incoming light (i.<wbr/>e.<wbr/> pixels that
-are stuck at an arbitrary value).<wbr/></p>
+              <p>Hotpixel correction interpolates out,<wbr/> or otherwise removes,<wbr/> pixels
+that do not accurately measure the incoming light (i.<wbr/>e.<wbr/> pixels that
+are stuck at an arbitrary value or are oversensitive).<wbr/></p>
             </td>
           </tr>
 
@@ -9022,7 +9204,7 @@ are stuck at an arbitrary value).<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The set of hot pixel correction modes that are supported by this
+              <p>List of hot pixel correction modes for <a href="#controls_android.hotPixel.mode">android.<wbr/>hot<wbr/>Pixel.<wbr/>mode</a> that are supported by this
 camera device.<wbr/></p>
             </td>
 
@@ -9030,6 +9212,7 @@ camera device.<wbr/></p>
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.hotPixel.mode">android.<wbr/>hot<wbr/>Pixel.<wbr/>mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -9045,8 +9228,7 @@ camera device.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This tag lists valid modes for <a href="#controls_android.hotPixel.mode">android.<wbr/>hot<wbr/>Pixel.<wbr/>mode</a>.<wbr/></p>
-<p>FULL mode camera devices will always support FAST.<wbr/></p>
+              <p>FULL mode camera devices will always support FAST.<wbr/></p>
             </td>
           </tr>
 
@@ -9130,13 +9312,14 @@ of reducing frame rate relative to sensor raw output.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Set operational mode for hot pixel correction.<wbr/></p>
+              <p>Operational mode for hot pixel correction.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.hotPixel.availableHotPixelModes">android.<wbr/>hot<wbr/>Pixel.<wbr/>available<wbr/>Hot<wbr/>Pixel<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -9152,11 +9335,9 @@ of reducing frame rate relative to sensor raw output.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Valid modes for this camera device are listed in
-<a href="#static_android.hotPixel.availableHotPixelModes">android.<wbr/>hot<wbr/>Pixel.<wbr/>available<wbr/>Hot<wbr/>Pixel<wbr/>Modes</a>.<wbr/></p>
-<p>Hotpixel correction interpolates out,<wbr/> or otherwise removes,<wbr/> pixels
-that do not accurately encode the incoming light (i.<wbr/>e.<wbr/> pixels that
-are stuck at an arbitrary value).<wbr/></p>
+              <p>Hotpixel correction interpolates out,<wbr/> or otherwise removes,<wbr/> pixels
+that do not accurately measure the incoming light (i.<wbr/>e.<wbr/> pixels that
+are stuck at an arbitrary value or are oversensitive).<wbr/></p>
             </td>
           </tr>
 
@@ -9199,7 +9380,7 @@ are stuck at an arbitrary value).<wbr/></p>
                 
           <tr class="entry" id="controls_android.jpeg.gpsLocation">
             <td class="entry_name
-             " rowspan="1">
+             " rowspan="3">
               android.<wbr/>jpeg.<wbr/>gps<wbr/>Location
             </td>
             <td class="entry_type">
@@ -9230,6 +9411,16 @@ are stuck at an arbitrary value).<wbr/></p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>Setting a location object in a request will include the GPS coordinates of the location
+into any JPEG images captured based on the request.<wbr/> These coordinates can then be
+viewed by anyone who receives the JPEG image.<wbr/></p>
+            </td>
+          </tr>
 
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
@@ -9261,7 +9452,7 @@ are stuck at an arbitrary value).<wbr/></p>
 
             <td class="entry_description">
               <p>GPS coordinates to include in output JPEG
-EXIF</p>
+EXIF.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -9304,7 +9495,7 @@ EXIF</p>
 
             <td class="entry_description">
               <p>32 characters describing GPS algorithm to
-include in EXIF</p>
+include in EXIF.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -9347,7 +9538,7 @@ include in EXIF</p>
 
             <td class="entry_description">
               <p>Time GPS fix was made to include in
-EXIF</p>
+EXIF.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -9372,7 +9563,7 @@ EXIF</p>
                 
           <tr class="entry" id="controls_android.jpeg.orientation">
             <td class="entry_name
-             " rowspan="1">
+             " rowspan="3">
               android.<wbr/>jpeg.<wbr/>orientation
             </td>
             <td class="entry_type">
@@ -9389,8 +9580,7 @@ EXIF</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Orientation of JPEG image to
-write</p>
+              <p>The orientation for a JPEG image.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -9408,6 +9598,40 @@ write</p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>The clockwise rotation angle in degrees,<wbr/> relative to the orientation
+to the camera,<wbr/> that the JPEG picture needs to be rotated by,<wbr/> to be viewed
+upright.<wbr/></p>
+<p>Camera devices may either encode this value into the JPEG EXIF header,<wbr/> or
+rotate the image data to match this orientation.<wbr/></p>
+<p>Note that this orientation is relative to the orientation of the camera sensor,<wbr/> given
+by <a href="#static_android.sensor.orientation">android.<wbr/>sensor.<wbr/>orientation</a>.<wbr/></p>
+<p>To translate from the device orientation given by the Android sensor APIs,<wbr/> the following
+sample code may be used:</p>
+<pre><code>private int getJpegOrientation(CameraCharacteristics c,<wbr/> int deviceOrientation) {
+    if (deviceOrientation == android.<wbr/>view.<wbr/>Orientation<wbr/>Event<wbr/>Listener.<wbr/>ORIENTATION_<wbr/>UNKNOWN) return 0;
+    int sensorOrientation = c.<wbr/>get(Camera<wbr/>Characteristics.<wbr/>SENSOR_<wbr/>ORIENTATION);
+
+    //<wbr/> Round device orientation to a multiple of 90
+    deviceOrientation = (deviceOrientation + 45) /<wbr/> 90 * 90;
+
+    //<wbr/> Reverse device orientation for front-facing cameras
+    boolean facingFront = c.<wbr/>get(Camera<wbr/>Characteristics.<wbr/>LENS_<wbr/>FACING) == Camera<wbr/>Characteristics.<wbr/>LENS_<wbr/>FACING_<wbr/>FRONT;
+    if (facingFront) deviceOrientation = -deviceOrientation;
+
+    //<wbr/> Calculate desired JPEG orientation relative to camera orientation to make
+    //<wbr/> the image upright relative to the device orientation
+    int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360;
+
+    return jpegOrientation;
+}
+</code></pre>
+            </td>
+          </tr>
 
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
@@ -9538,7 +9762,7 @@ thumbnail.<wbr/></p>
             </td>
 
             <td class="entry_range">
-              <p>Size must be one of the size from <a href="#static_android.jpeg.availableThumbnailSizes">android.<wbr/>jpeg.<wbr/>available<wbr/>Thumbnail<wbr/>Sizes</a></p>
+              <p><a href="#static_android.jpeg.availableThumbnailSizes">android.<wbr/>jpeg.<wbr/>available<wbr/>Thumbnail<wbr/>Sizes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -9555,8 +9779,8 @@ thumbnail.<wbr/></p>
             <td class="entry_details" colspan="5">
               <p>When set to (0,<wbr/> 0) value,<wbr/> the JPEG EXIF will not contain thumbnail,<wbr/>
 but the captured JPEG will still be a valid image.<wbr/></p>
-<p>When a jpeg image capture is issued,<wbr/> the thumbnail size selected should have
-the same aspect ratio as the jpeg image.<wbr/></p>
+<p>For best results,<wbr/> when issuing a request for a JPEG image,<wbr/> the thumbnail size selected
+should have the same aspect ratio as the main JPEG output.<wbr/></p>
 <p>If the thumbnail image aspect ratio differs from the JPEG primary image aspect
 ratio,<wbr/> the camera device creates the thumbnail by cropping it from the primary image.<wbr/>
 For example,<wbr/> if the primary image has 4:3 aspect ratio,<wbr/> the thumbnail image has
@@ -9632,15 +9856,14 @@ thumbnail image cropping.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Supported resolutions for the JPEG thumbnail.<wbr/></p>
+              <p>List of JPEG thumbnail sizes for <a href="#controls_android.jpeg.thumbnailSize">android.<wbr/>jpeg.<wbr/>thumbnail<wbr/>Size</a> supported by this
+camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
-              <p>Will include at least one valid resolution,<wbr/> plus
-(0,<wbr/>0) for no thumbnail generation,<wbr/> and each size will be distinct.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -9655,7 +9878,9 @@ thumbnail image cropping.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Below condiditions will be satisfied for this size list:</p>
+              <p>This list will include at least one non-zero resolution,<wbr/> plus <code>(0,<wbr/>0)</code> for indicating no
+thumbnail should be generated.<wbr/></p>
+<p>Below condiditions will be satisfied for this size list:</p>
 <ul>
 <li>The sizes will be sorted by increasing pixel area (width x height).<wbr/>
 If several resolutions have the same area,<wbr/> they will be sorted by increasing width.<wbr/></li>
@@ -9666,7 +9891,7 @@ in a given size list.<wbr/></li>
 <li>Each output JPEG size in <a href="#static_android.scaler.availableStreamConfigurations">android.<wbr/>scaler.<wbr/>available<wbr/>Stream<wbr/>Configurations</a> will have at least
 one corresponding size that has the same aspect ratio in availableThumbnailSizes,<wbr/>
 and vice versa.<wbr/></li>
-<li>All non (0,<wbr/> 0) sizes will have non-zero widths and heights.<wbr/></li>
+<li>All non-<code>(0,<wbr/> 0)</code> sizes will have non-zero widths and heights.<wbr/></li>
 </ul>
             </td>
           </tr>
@@ -9754,7 +9979,7 @@ JPEG</p>
                 
           <tr class="entry" id="dynamic_android.jpeg.gpsLocation">
             <td class="entry_name
-             " rowspan="1">
+             " rowspan="3">
               android.<wbr/>jpeg.<wbr/>gps<wbr/>Location
             </td>
             <td class="entry_type">
@@ -9785,6 +10010,16 @@ JPEG</p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>Setting a location object in a request will include the GPS coordinates of the location
+into any JPEG images captured based on the request.<wbr/> These coordinates can then be
+viewed by anyone who receives the JPEG image.<wbr/></p>
+            </td>
+          </tr>
 
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
@@ -9816,7 +10051,7 @@ JPEG</p>
 
             <td class="entry_description">
               <p>GPS coordinates to include in output JPEG
-EXIF</p>
+EXIF.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -9859,7 +10094,7 @@ EXIF</p>
 
             <td class="entry_description">
               <p>32 characters describing GPS algorithm to
-include in EXIF</p>
+include in EXIF.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -9902,7 +10137,7 @@ include in EXIF</p>
 
             <td class="entry_description">
               <p>Time GPS fix was made to include in
-EXIF</p>
+EXIF.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -9927,7 +10162,7 @@ EXIF</p>
                 
           <tr class="entry" id="dynamic_android.jpeg.orientation">
             <td class="entry_name
-             " rowspan="1">
+             " rowspan="3">
               android.<wbr/>jpeg.<wbr/>orientation
             </td>
             <td class="entry_type">
@@ -9944,8 +10179,7 @@ EXIF</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Orientation of JPEG image to
-write</p>
+              <p>The orientation for a JPEG image.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -9963,6 +10197,40 @@ write</p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>The clockwise rotation angle in degrees,<wbr/> relative to the orientation
+to the camera,<wbr/> that the JPEG picture needs to be rotated by,<wbr/> to be viewed
+upright.<wbr/></p>
+<p>Camera devices may either encode this value into the JPEG EXIF header,<wbr/> or
+rotate the image data to match this orientation.<wbr/></p>
+<p>Note that this orientation is relative to the orientation of the camera sensor,<wbr/> given
+by <a href="#static_android.sensor.orientation">android.<wbr/>sensor.<wbr/>orientation</a>.<wbr/></p>
+<p>To translate from the device orientation given by the Android sensor APIs,<wbr/> the following
+sample code may be used:</p>
+<pre><code>private int getJpegOrientation(CameraCharacteristics c,<wbr/> int deviceOrientation) {
+    if (deviceOrientation == android.<wbr/>view.<wbr/>Orientation<wbr/>Event<wbr/>Listener.<wbr/>ORIENTATION_<wbr/>UNKNOWN) return 0;
+    int sensorOrientation = c.<wbr/>get(Camera<wbr/>Characteristics.<wbr/>SENSOR_<wbr/>ORIENTATION);
+
+    //<wbr/> Round device orientation to a multiple of 90
+    deviceOrientation = (deviceOrientation + 45) /<wbr/> 90 * 90;
+
+    //<wbr/> Reverse device orientation for front-facing cameras
+    boolean facingFront = c.<wbr/>get(Camera<wbr/>Characteristics.<wbr/>LENS_<wbr/>FACING) == Camera<wbr/>Characteristics.<wbr/>LENS_<wbr/>FACING_<wbr/>FRONT;
+    if (facingFront) deviceOrientation = -deviceOrientation;
+
+    //<wbr/> Calculate desired JPEG orientation relative to camera orientation to make
+    //<wbr/> the image upright relative to the device orientation
+    int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360;
+
+    return jpegOrientation;
+}
+</code></pre>
+            </td>
+          </tr>
 
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
@@ -10150,7 +10418,7 @@ thumbnail.<wbr/></p>
             </td>
 
             <td class="entry_range">
-              <p>Size must be one of the size from <a href="#static_android.jpeg.availableThumbnailSizes">android.<wbr/>jpeg.<wbr/>available<wbr/>Thumbnail<wbr/>Sizes</a></p>
+              <p><a href="#static_android.jpeg.availableThumbnailSizes">android.<wbr/>jpeg.<wbr/>available<wbr/>Thumbnail<wbr/>Sizes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -10167,8 +10435,8 @@ thumbnail.<wbr/></p>
             <td class="entry_details" colspan="5">
               <p>When set to (0,<wbr/> 0) value,<wbr/> the JPEG EXIF will not contain thumbnail,<wbr/>
 but the captured JPEG will still be a valid image.<wbr/></p>
-<p>When a jpeg image capture is issued,<wbr/> the thumbnail size selected should have
-the same aspect ratio as the jpeg image.<wbr/></p>
+<p>For best results,<wbr/> when issuing a request for a JPEG image,<wbr/> the thumbnail size selected
+should have the same aspect ratio as the main JPEG output.<wbr/></p>
 <p>If the thumbnail image aspect ratio differs from the JPEG primary image aspect
 ratio,<wbr/> the camera device creates the thumbnail by cropping it from the primary image.<wbr/>
 For example,<wbr/> if the primary image has 4:3 aspect ratio,<wbr/> the thumbnail image has
@@ -10245,12 +10513,12 @@ thumbnail image cropping.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The ratio of lens focal length to the effective
-aperture diameter.<wbr/></p>
+              <p>The desired lens aperture size,<wbr/> as a ratio of lens focal length to the
+effective aperture diameter.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              f-number (f/<wbr/>NNN)
+              The f-number (f/<wbr/>N)
             </td>
 
             <td class="entry_range">
@@ -10269,9 +10537,8 @@ aperture diameter.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This will only be supported on the camera devices that
-have variable aperture lens.<wbr/> The aperture value can only be
-one of the values listed in <a href="#static_android.lens.info.availableApertures">android.<wbr/>lens.<wbr/>info.<wbr/>available<wbr/>Apertures</a>.<wbr/></p>
+              <p>Setting this value is only supported on the camera devices that have a variable
+aperture lens.<wbr/></p>
 <p>When this is supported and <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> is OFF,<wbr/>
 this can be set along with <a href="#controls_android.sensor.exposureTime">android.<wbr/>sensor.<wbr/>exposure<wbr/>Time</a>,<wbr/>
 <a href="#controls_android.sensor.sensitivity">android.<wbr/>sensor.<wbr/>sensitivity</a>,<wbr/> and <a href="#controls_android.sensor.frameDuration">android.<wbr/>sensor.<wbr/>frame<wbr/>Duration</a>
@@ -10311,11 +10578,11 @@ back to the user in the corresponding result.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>State of lens neutral density filter(s).<wbr/></p>
+              <p>The desired setting for the lens neutral density filter(s).<wbr/></p>
             </td>
 
             <td class="entry_units">
-              Steps of Exposure Value (EV).<wbr/>
+              Exposure Value (EV)
             </td>
 
             <td class="entry_range">
@@ -10334,9 +10601,7 @@ back to the user in the corresponding result.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This will not be supported on most camera devices.<wbr/> On devices
-where this is supported,<wbr/> this may only be set to one of the
-values included in <a href="#static_android.lens.info.availableFilterDensities">android.<wbr/>lens.<wbr/>info.<wbr/>available<wbr/>Filter<wbr/>Densities</a>.<wbr/></p>
+              <p>This control will not be supported on most camera devices.<wbr/></p>
 <p>Lens filters are typically used to lower the amount of light the
 sensor is exposed to (measured in steps of EV).<wbr/> As used here,<wbr/> an EV
 step is the standard logarithmic representation,<wbr/> which are
@@ -10375,11 +10640,11 @@ to the requested value.<wbr/> While the filter density is still changing,<wbr/>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The current lens focal length; used for optical zoom.<wbr/></p>
+              <p>The desired lens focal length; used for optical zoom.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              focal length in mm
+              Millimeters
             </td>
 
             <td class="entry_range">
@@ -10406,7 +10671,7 @@ setting won't be applied instantaneously,<wbr/> and it may take several
 frames before the lens can change to the requested focal length.<wbr/>
 While the focal length is still changing,<wbr/> <a href="#dynamic_android.lens.state">android.<wbr/>lens.<wbr/>state</a> will
 be set to MOVING.<wbr/></p>
-<p>This is expected not to be supported on most devices.<wbr/></p>
+<p>Optical zoom will not be supported on most devices.<wbr/></p>
             </td>
           </tr>
 
@@ -10434,12 +10699,12 @@ be set to MOVING.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Distance to plane of sharpest focus,<wbr/>
+              <p>Desired distance to plane of sharpest focus,<wbr/>
 measured from frontmost surface of the lens.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
+              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details
             </td>
 
             <td class="entry_range">
@@ -10459,8 +10724,11 @@ measured from frontmost surface of the lens.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p><code>0.<wbr/>0f</code> means infinity focus.<wbr/> Used value will be clamped
-to <code>[0.<wbr/>0f,<wbr/> <a href="#static_android.lens.info.minimumFocusDistance">android.<wbr/>lens.<wbr/>info.<wbr/>minimum<wbr/>Focus<wbr/>Distance</a>]</code>.<wbr/></p>
+              <p>This control can be used for setting manual focus,<wbr/> on devices that support
+the MANUAL_<wbr/>SENSOR capability and have a variable-focus lens (see
+<a href="#static_android.lens.info.minimumFocusDistance">android.<wbr/>lens.<wbr/>info.<wbr/>minimum<wbr/>Focus<wbr/>Distance</a>).<wbr/></p>
+<p>A value of <code>0.<wbr/>0f</code> means infinity focus.<wbr/> The value set will be clamped to
+<code>[0.<wbr/>0f,<wbr/> <a href="#static_android.lens.info.minimumFocusDistance">android.<wbr/>lens.<wbr/>info.<wbr/>minimum<wbr/>Focus<wbr/>Distance</a>]</code>.<wbr/></p>
 <p>Like <a href="#controls_android.lens.focalLength">android.<wbr/>lens.<wbr/>focal<wbr/>Length</a>,<wbr/> this setting won't be applied
 instantaneously,<wbr/> and it may take several frames before the lens
 can move to the requested focus distance.<wbr/> While the lens is still moving,<wbr/>
@@ -10539,9 +10807,9 @@ frames to initialize,<wbr/> the camera device will report the current mode in
 capture result metadata.<wbr/> For example,<wbr/> When "ON" mode is requested,<wbr/> the
 optical stabilization modes in the first several capture results may still
 be "OFF",<wbr/> and it will become "ON" when the initialization is done.<wbr/></p>
-<p>If a camera device supports both OIS and EIS (<a href="#controls_android.control.videoStabilizationMode">android.<wbr/>control.<wbr/>video<wbr/>Stabilization<wbr/>Mode</a>),<wbr/>
-turning both modes on may produce undesirable interaction,<wbr/> so it is recommended not
-to enable both at the same time.<wbr/></p>
+<p>If a camera device supports both OIS and digital image stabilization
+(<a href="#controls_android.control.videoStabilizationMode">android.<wbr/>control.<wbr/>video<wbr/>Stabilization<wbr/>Mode</a>),<wbr/> turning both modes on may produce undesirable
+interaction,<wbr/> so it is recommended not to enable both at the same time.<wbr/></p>
 <p>Not all devices will support OIS; see
 <a href="#static_android.lens.info.availableOpticalStabilization">android.<wbr/>lens.<wbr/>info.<wbr/>available<wbr/>Optical<wbr/>Stabilization</a> for
 available controls.<wbr/></p>
@@ -10605,15 +10873,15 @@ available controls.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of supported aperture
-values.<wbr/></p>
+              <p>List of aperture size values for <a href="#controls_android.lens.aperture">android.<wbr/>lens.<wbr/>aperture</a> that are
+supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              The aperture f-number
             </td>
 
             <td class="entry_range">
-              <p>one entry required,<wbr/> &gt; 0</p>
             </td>
 
             <td class="entry_tags">
@@ -10628,9 +10896,9 @@ values.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If the camera device doesn't support variable apertures,<wbr/>
-listed value will be the fixed aperture.<wbr/></p>
-<p>If the camera device supports variable apertures,<wbr/> the aperture value
+              <p>If the camera device doesn't support a variable lens aperture,<wbr/>
+this list will contain only one value,<wbr/> which is the fixed aperture size.<wbr/></p>
+<p>If the camera device supports a variable aperture,<wbr/> the aperture values
 in this list will be sorted in ascending order.<wbr/></p>
             </td>
           </tr>
@@ -10663,15 +10931,16 @@ in this list will be sorted in ascending order.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of supported neutral density filter values for
-<a href="#controls_android.lens.filterDensity">android.<wbr/>lens.<wbr/>filter<wbr/>Density</a>.<wbr/></p>
+              <p>List of neutral density filter values for
+<a href="#controls_android.lens.filterDensity">android.<wbr/>lens.<wbr/>filter<wbr/>Density</a> that are supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Exposure value (EV)
             </td>
 
             <td class="entry_range">
-              <p>At least one value is required.<wbr/> Values must be &gt;= 0.<wbr/></p>
+              <p>Values are &gt;= 0</p>
             </td>
 
             <td class="entry_tags">
@@ -10686,10 +10955,9 @@ in this list will be sorted in ascending order.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If changing <a href="#controls_android.lens.filterDensity">android.<wbr/>lens.<wbr/>filter<wbr/>Density</a> is not supported,<wbr/>
-availableFilterDensities must contain only 0.<wbr/> Otherwise,<wbr/> this
-list contains only the exact filter density values available on
-this camera device.<wbr/></p>
+              <p>If a neutral density filter is not supported by this camera device,<wbr/>
+this list will contain only 0.<wbr/> Otherwise,<wbr/> this list will include every
+filter density supported by the camera device,<wbr/> in ascending order.<wbr/></p>
             </td>
           </tr>
 
@@ -10722,16 +10990,16 @@ this camera device.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The available focal lengths for this device for use with
-<a href="#controls_android.lens.focalLength">android.<wbr/>lens.<wbr/>focal<wbr/>Length</a>.<wbr/></p>
+              <p>List of focal lengths for <a href="#controls_android.lens.focalLength">android.<wbr/>lens.<wbr/>focal<wbr/>Length</a> that are supported by this camera
+device.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Millimeters
             </td>
 
             <td class="entry_range">
-              <p>Each value in this list must be &gt; 0.<wbr/> This list must
-contain at least one value.<wbr/></p>
+              <p>Values are &gt; 0</p>
             </td>
 
             <td class="entry_tags">
@@ -10747,10 +11015,10 @@ contain at least one value.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If optical zoom is not supported,<wbr/> this will only report
-a single value corresponding to the static focal length of the
-device.<wbr/> Otherwise,<wbr/> this will report every focal length supported
-by the device.<wbr/></p>
+              <p>If optical zoom is not supported,<wbr/> this list will only contain
+a single value corresponding to the fixed focal length of the
+device.<wbr/> Otherwise,<wbr/> this list will include every focal length supported
+by the camera device,<wbr/> in ascending order.<wbr/></p>
             </td>
           </tr>
 
@@ -10783,15 +11051,15 @@ by the device.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List containing a subset of the optical image
-stabilization (OIS) modes specified in
-<a href="#controls_android.lens.opticalStabilizationMode">android.<wbr/>lens.<wbr/>optical<wbr/>Stabilization<wbr/>Mode</a>.<wbr/></p>
+              <p>List of optical image stabilization (OIS) modes for
+<a href="#controls_android.lens.opticalStabilizationMode">android.<wbr/>lens.<wbr/>optical<wbr/>Stabilization<wbr/>Mode</a> that are supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.lens.opticalStabilizationMode">android.<wbr/>lens.<wbr/>optical<wbr/>Stabilization<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -10806,7 +11074,7 @@ stabilization (OIS) modes specified in
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If OIS is not implemented for a given camera device,<wbr/> this will
+              <p>If OIS is not supported by a given camera device,<wbr/> this list will
 contain only OFF.<wbr/></p>
             </td>
           </tr>
@@ -10835,16 +11103,16 @@ contain only OFF.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Optional.<wbr/> Hyperfocal distance for this lens.<wbr/></p>
+              <p>Hyperfocal distance for this lens.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
+              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details
             </td>
 
             <td class="entry_range">
-              <p>If lens is fixed focus,<wbr/> &gt;= 0.<wbr/> If lens has focuser unit,<wbr/> the range is
-<code>(0,<wbr/> <a href="#static_android.lens.info.minimumFocusDistance">android.<wbr/>lens.<wbr/>info.<wbr/>minimum<wbr/>Focus<wbr/>Distance</a>]</code></p>
+              <p>If lens is fixed focus,<wbr/> &gt;= 0.<wbr/> If lens has focuser unit,<wbr/> the value is
+within <code>(0.<wbr/>0f,<wbr/> <a href="#static_android.lens.info.minimumFocusDistance">android.<wbr/>lens.<wbr/>info.<wbr/>minimum<wbr/>Focus<wbr/>Distance</a>]</code></p>
             </td>
 
             <td class="entry_tags">
@@ -10886,11 +11154,11 @@ field when <a href="#static_android.lens.info.focusDistanceCalibration">android.
 
             <td class="entry_description">
               <p>Shortest distance from frontmost surface
-of the lens that can be focused correctly.<wbr/></p>
+of the lens that can be brought into sharp focus.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
+              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details
             </td>
 
             <td class="entry_range">
@@ -10909,7 +11177,7 @@ of the lens that can be focused correctly.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If the lens is fixed-focus,<wbr/> this should be
+              <p>If the lens is fixed-focus,<wbr/> this will be
 0.<wbr/></p>
             </td>
           </tr>
@@ -11063,6 +11331,15 @@ of best focus.<wbr/></p></span>
 focus related metadata entries,<wbr/> i.<wbr/>e.<wbr/> <a href="#controls_android.lens.focusDistance">android.<wbr/>lens.<wbr/>focus<wbr/>Distance</a>,<wbr/>
 <a href="#dynamic_android.lens.focusRange">android.<wbr/>lens.<wbr/>focus<wbr/>Range</a>,<wbr/> <a href="#static_android.lens.info.hyperfocalDistance">android.<wbr/>lens.<wbr/>info.<wbr/>hyperfocal<wbr/>Distance</a>,<wbr/> and
 <a href="#static_android.lens.info.minimumFocusDistance">android.<wbr/>lens.<wbr/>info.<wbr/>minimum<wbr/>Focus<wbr/>Distance</a>.<wbr/></p>
+<p>APPROXIMATE and CALIBRATED devices report the focus metadata in
+units of diopters (1/<wbr/>meter),<wbr/> so <code>0.<wbr/>0f</code> represents focusing at infinity,<wbr/>
+and increasing positive numbers represent focusing closer and closer
+to the camera device.<wbr/> The focus distance control also uses diopters
+on these devices.<wbr/></p>
+<p>UNCALIBRATED devices do not use units that are directly comparable
+to any real physical measurement,<wbr/> but <code>0.<wbr/>0f</code> still represents farthest
+focus,<wbr/> and <a href="#static_android.lens.info.minimumFocusDistance">android.<wbr/>lens.<wbr/>info.<wbr/>minimum<wbr/>Focus<wbr/>Distance</a> represents the
+nearest focus the device can achieve.<wbr/></p>
             </td>
           </tr>
 
@@ -11292,12 +11569,12 @@ device</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The ratio of lens focal length to the effective
-aperture diameter.<wbr/></p>
+              <p>The desired lens aperture size,<wbr/> as a ratio of lens focal length to the
+effective aperture diameter.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              f-number (f/<wbr/>NNN)
+              The f-number (f/<wbr/>N)
             </td>
 
             <td class="entry_range">
@@ -11316,9 +11593,8 @@ aperture diameter.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This will only be supported on the camera devices that
-have variable aperture lens.<wbr/> The aperture value can only be
-one of the values listed in <a href="#static_android.lens.info.availableApertures">android.<wbr/>lens.<wbr/>info.<wbr/>available<wbr/>Apertures</a>.<wbr/></p>
+              <p>Setting this value is only supported on the camera devices that have a variable
+aperture lens.<wbr/></p>
 <p>When this is supported and <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> is OFF,<wbr/>
 this can be set along with <a href="#controls_android.sensor.exposureTime">android.<wbr/>sensor.<wbr/>exposure<wbr/>Time</a>,<wbr/>
 <a href="#controls_android.sensor.sensitivity">android.<wbr/>sensor.<wbr/>sensitivity</a>,<wbr/> and <a href="#controls_android.sensor.frameDuration">android.<wbr/>sensor.<wbr/>frame<wbr/>Duration</a>
@@ -11358,11 +11634,11 @@ back to the user in the corresponding result.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>State of lens neutral density filter(s).<wbr/></p>
+              <p>The desired setting for the lens neutral density filter(s).<wbr/></p>
             </td>
 
             <td class="entry_units">
-              Steps of Exposure Value (EV).<wbr/>
+              Exposure Value (EV)
             </td>
 
             <td class="entry_range">
@@ -11381,9 +11657,7 @@ back to the user in the corresponding result.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This will not be supported on most camera devices.<wbr/> On devices
-where this is supported,<wbr/> this may only be set to one of the
-values included in <a href="#static_android.lens.info.availableFilterDensities">android.<wbr/>lens.<wbr/>info.<wbr/>available<wbr/>Filter<wbr/>Densities</a>.<wbr/></p>
+              <p>This control will not be supported on most camera devices.<wbr/></p>
 <p>Lens filters are typically used to lower the amount of light the
 sensor is exposed to (measured in steps of EV).<wbr/> As used here,<wbr/> an EV
 step is the standard logarithmic representation,<wbr/> which are
@@ -11422,11 +11696,11 @@ to the requested value.<wbr/> While the filter density is still changing,<wbr/>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The current lens focal length; used for optical zoom.<wbr/></p>
+              <p>The desired lens focal length; used for optical zoom.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              focal length in mm
+              Millimeters
             </td>
 
             <td class="entry_range">
@@ -11453,7 +11727,7 @@ setting won't be applied instantaneously,<wbr/> and it may take several
 frames before the lens can change to the requested focal length.<wbr/>
 While the focal length is still changing,<wbr/> <a href="#dynamic_android.lens.state">android.<wbr/>lens.<wbr/>state</a> will
 be set to MOVING.<wbr/></p>
-<p>This is expected not to be supported on most devices.<wbr/></p>
+<p>Optical zoom will not be supported on most devices.<wbr/></p>
             </td>
           </tr>
 
@@ -11481,12 +11755,12 @@ be set to MOVING.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Distance to plane of sharpest focus,<wbr/>
+              <p>Desired distance to plane of sharpest focus,<wbr/>
 measured from frontmost surface of the lens.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
+              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details
             </td>
 
             <td class="entry_range">
@@ -11543,8 +11817,8 @@ sharp focus (depth of field).<wbr/></p>
             </td>
 
             <td class="entry_units">
-              pair of focus distances in diopters: (near,<wbr/>
-          far),<wbr/> see android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
+              A pair of focus distances in diopters: (near,<wbr/>
+          far); see android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
             </td>
 
             <td class="entry_range">
@@ -11637,9 +11911,9 @@ frames to initialize,<wbr/> the camera device will report the current mode in
 capture result metadata.<wbr/> For example,<wbr/> When "ON" mode is requested,<wbr/> the
 optical stabilization modes in the first several capture results may still
 be "OFF",<wbr/> and it will become "ON" when the initialization is done.<wbr/></p>
-<p>If a camera device supports both OIS and EIS (<a href="#controls_android.control.videoStabilizationMode">android.<wbr/>control.<wbr/>video<wbr/>Stabilization<wbr/>Mode</a>),<wbr/>
-turning both modes on may produce undesirable interaction,<wbr/> so it is recommended not
-to enable both at the same time.<wbr/></p>
+<p>If a camera device supports both OIS and digital image stabilization
+(<a href="#controls_android.control.videoStabilizationMode">android.<wbr/>control.<wbr/>video<wbr/>Stabilization<wbr/>Mode</a>),<wbr/> turning both modes on may produce undesirable
+interaction,<wbr/> so it is recommended not to enable both at the same time.<wbr/></p>
 <p>Not all devices will support OIS; see
 <a href="#static_android.lens.info.availableOpticalStabilization">android.<wbr/>lens.<wbr/>info.<wbr/>available<wbr/>Optical<wbr/>Stabilization</a> for
 available controls.<wbr/></p>
@@ -11806,6 +12080,7 @@ relative to sensor output.<wbr/></p></span>
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.noiseReduction.availableNoiseReductionModes">android.<wbr/>noise<wbr/>Reduction.<wbr/>available<wbr/>Noise<wbr/>Reduction<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -11820,10 +12095,9 @@ relative to sensor output.<wbr/></p></span>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Noise filtering control.<wbr/> OFF means no noise reduction
-will be applied by the camera device.<wbr/></p>
-<p>This must be set to a valid mode from
-<a href="#static_android.noiseReduction.availableNoiseReductionModes">android.<wbr/>noise<wbr/>Reduction.<wbr/>available<wbr/>Noise<wbr/>Reduction<wbr/>Modes</a>.<wbr/></p>
+              <p>The noise reduction algorithm attempts to improve image quality by removing
+excessive noise added by the capture process,<wbr/> especially in dark conditions.<wbr/>
+OFF means no noise reduction will be applied by the camera device.<wbr/></p>
 <p>FAST/<wbr/>HIGH_<wbr/>QUALITY both mean camera device determined noise filtering
 will be applied.<wbr/> HIGH_<wbr/>QUALITY mode indicates that the camera device
 will use the highest-quality noise filtering algorithms,<wbr/>
@@ -11931,13 +12205,15 @@ applied to the images</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The set of noise reduction modes supported by this camera device.<wbr/></p>
+              <p>List of noise reduction modes for <a href="#controls_android.noiseReduction.mode">android.<wbr/>noise<wbr/>Reduction.<wbr/>mode</a> that are supported
+by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.noiseReduction.mode">android.<wbr/>noise<wbr/>Reduction.<wbr/>mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -11952,8 +12228,7 @@ applied to the images</p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This tag lists the valid modes for <a href="#controls_android.noiseReduction.mode">android.<wbr/>noise<wbr/>Reduction.<wbr/>mode</a>.<wbr/></p>
-<p>Full-capability camera devices must always support OFF and FAST.<wbr/></p>
+              <p>Full-capability camera devices will always support OFF and FAST.<wbr/></p>
 <p>Legacy-capability camera devices will only support FAST mode.<wbr/></p>
             </td>
           </tr>
@@ -12032,6 +12307,7 @@ relative to sensor output.<wbr/></p></span>
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.noiseReduction.availableNoiseReductionModes">android.<wbr/>noise<wbr/>Reduction.<wbr/>available<wbr/>Noise<wbr/>Reduction<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -12046,10 +12322,9 @@ relative to sensor output.<wbr/></p></span>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Noise filtering control.<wbr/> OFF means no noise reduction
-will be applied by the camera device.<wbr/></p>
-<p>This must be set to a valid mode from
-<a href="#static_android.noiseReduction.availableNoiseReductionModes">android.<wbr/>noise<wbr/>Reduction.<wbr/>available<wbr/>Noise<wbr/>Reduction<wbr/>Modes</a>.<wbr/></p>
+              <p>The noise reduction algorithm attempts to improve image quality by removing
+excessive noise added by the capture process,<wbr/> especially in dark conditions.<wbr/>
+OFF means no noise reduction will be applied by the camera device.<wbr/></p>
 <p>FAST/<wbr/>HIGH_<wbr/>QUALITY both mean camera device determined noise filtering
 will be applied.<wbr/> HIGH_<wbr/>QUALITY mode indicates that the camera device
 will use the highest-quality noise filtering algorithms,<wbr/>
@@ -13021,7 +13296,7 @@ Typically:</p>
 </ul>
 <p>For full guarantees,<wbr/> query StreamConfigurationMap#getOutputStallDuration with
 a processed format -- it will return 0 for a non-stalling stream.<wbr/></p>
-<p>LEGACY devices will support up to 3 processing/<wbr/>non-stalling streams.<wbr/></p>
+<p>LEGACY devices will support at least 2 processing/<wbr/>non-stalling streams.<wbr/></p>
             </td>
           </tr>
 
@@ -13078,7 +13353,7 @@ the camera device.<wbr/> Using more streams simultaneously may require more hard
 CPU resources that will consume more power.<wbr/> The image format for this kind of an output stream can
 be any non-<code>RAW</code> and supported format provided by <a href="#static_android.scaler.streamConfigurationMap">android.<wbr/>scaler.<wbr/>stream<wbr/>Configuration<wbr/>Map</a>.<wbr/></p>
 <p>A processed and stalling format is defined as any non-RAW format with a stallDurations &gt; 0.<wbr/>
-Typically only the <code>JPEG</code> format (ImageFormat#JPEG)</p>
+Typically only the <code>JPEG</code> format (ImageFormat#JPEG) is a stalling format.<wbr/></p>
 <p>For full guarantees,<wbr/> query StreamConfigurationMap#getOutputStallDuration with
 a processed format -- it will return a non-0 value for a stalling stream.<wbr/></p>
 <p>LEGACY devices will support up to 1 processing/<wbr/>stalling stream.<wbr/></p>
@@ -13481,7 +13756,7 @@ raw sensor images.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of capabilities that the camera device
+              <p>List of capabilities that this camera device
 advertises as fully supporting.<wbr/></p>
             </td>
 
@@ -13516,7 +13791,7 @@ to do this query each of <a href="#static_android.request.availableRequestKeys">
 <li>MANUAL_<wbr/>POST_<wbr/>PROCESSING</li>
 </ul>
 <p>Other capabilities may be available on either FULL or LIMITED
-devices,<wbr/> but the application should query this field to be sure.<wbr/></p>
+devices,<wbr/> but the application should query this key to be sure.<wbr/></p>
             </td>
           </tr>
 
@@ -13664,13 +13939,13 @@ to use with CaptureResult.<wbr/></p>
             <td class="entry_details" colspan="5">
               <p>Attempting to get a key from a CaptureResult that is not
 listed here will always return a <code>null</code> value.<wbr/> Getting a key from
-a CaptureResult that is listed here must never return a <code>null</code>
+a CaptureResult that is listed here will generally never return a <code>null</code>
 value.<wbr/></p>
 <p>The following keys may return <code>null</code> unless they are enabled:</p>
 <ul>
 <li><a href="#dynamic_android.statistics.lensShadingMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map</a> (non-null iff <a href="#controls_android.statistics.lensShadingMapMode">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map<wbr/>Mode</a> == ON)</li>
 </ul>
-<p>(Those sometimes-null keys should nevertheless be listed here
+<p>(Those sometimes-null keys will nevertheless be listed here
 if they are available.<wbr/>)</p>
 <p>This field can be used to query the feature set of a camera device
 at a more granular level than capabilities.<wbr/> This is especially
@@ -13756,7 +14031,7 @@ details.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Tags listed here must always have an entry in the static info metadata,<wbr/>
+              <p>Keys listed here must always have an entry in the static info metadata,<wbr/>
 even if that size is 0 elements.<wbr/> Only array-type tags (e.<wbr/>g.<wbr/> lists,<wbr/>
 matrices,<wbr/> strings) are allowed to have 0 elements.<wbr/></p>
 <p>Vendor tags must not be listed here.<wbr/> Use the vendor tag metadata
@@ -14135,12 +14410,11 @@ pipeline stages were actually used.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The region of the sensor to read out for this capture.<wbr/></p>
+              <p>The desired region of the sensor to read out for this capture.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              (x,<wbr/>y) of top-left corner,<wbr/> width and height of region
-          in pixels; (0,<wbr/>0) is top-left corner of
+              Pixel coordinates relative to
           android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
             </td>
 
@@ -14159,7 +14433,8 @@ pipeline stages were actually used.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>The crop region coordinate system is based off
+              <p>This control can be used to implement digital zoom.<wbr/></p>
+<p>The crop region coordinate system is based off
 <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with <code>(0,<wbr/> 0)</code> being the
 top-left corner of the sensor active array.<wbr/></p>
 <p>Output streams use this rectangle to produce their output,<wbr/>
@@ -14415,7 +14690,7 @@ for each resolution in <a href="#static_android.scaler.availableJpegSizes">andro
             </td>
 
             <td class="entry_units">
-              ns
+              Nanoseconds
             </td>
 
             <td class="entry_range">
@@ -14518,7 +14793,7 @@ and should include half/<wbr/>quarter of sensor maximum resolution.<wbr/></p>
                 
           <tr class="entry" id="static_android.scaler.availableMaxDigitalZoom">
             <td class="entry_name
-             " rowspan="1">
+             " rowspan="3">
               android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom
             </td>
             <td class="entry_type">
@@ -14537,16 +14812,11 @@ and should include half/<wbr/>quarter of sensor maximum resolution.<wbr/></p>
             <td class="entry_description">
               <p>The maximum ratio between both active area width
 and crop region width,<wbr/> and active area height and
-crop region height.<wbr/></p>
-<p>This represents the maximum amount of zooming possible by
-the camera device,<wbr/> or equivalently,<wbr/> the minimum cropping
-window size.<wbr/></p>
-<p>Crop regions that have a width or height that is smaller
-than this ratio allows will be rounded up to the minimum
-allowed size by the camera device.<wbr/></p>
+crop region height,<wbr/> for <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Zoom scale factor
             </td>
 
             <td class="entry_range">
@@ -14560,6 +14830,19 @@ allowed size by the camera device.<wbr/></p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>This represents the maximum amount of zooming possible by
+the camera device,<wbr/> or equivalently,<wbr/> the minimum cropping
+window size.<wbr/></p>
+<p>Crop regions that have a width or height that is smaller
+than this ratio allows will be rounded up to the minimum
+allowed size by the camera device.<wbr/></p>
+            </td>
+          </tr>
 
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
@@ -14596,12 +14879,11 @@ minimum supportable frame duration for that size.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              ns
+              Nanoseconds
             </td>
 
             <td class="entry_range">
               <p><span class="entry_range_deprecated">Deprecated</span>. Do not use.</p>
-              <p>TODO: Remove property.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -14664,7 +14946,6 @@ encoders.<wbr/></p>
 
             <td class="entry_range">
               <p><span class="entry_range_deprecated">Deprecated</span>. Do not use.</p>
-              <p>TODO: Remove property.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -14745,12 +15026,11 @@ supportable frame duration for that size.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              ns
+              Nanoseconds
             </td>
 
             <td class="entry_range">
               <p><span class="entry_range_deprecated">Deprecated</span>. Do not use.</p>
-              <p>TODO: Remove property.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -14812,8 +15092,6 @@ height</p>
 
             <td class="entry_range">
               <p><span class="entry_range_deprecated">Deprecated</span>. Do not use.</p>
-              <p>TODO: Remove property.<wbr/>
-Must include: - sensor maximum resolution.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -15618,12 +15896,11 @@ FREEFORM cropping.<wbr/> LEGACY capability devices will only support CENTER_<wbr
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The region of the sensor to read out for this capture.<wbr/></p>
+              <p>The desired region of the sensor to read out for this capture.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              (x,<wbr/>y) of top-left corner,<wbr/> width and height of region
-          in pixels; (0,<wbr/>0) is top-left corner of
+              Pixel coordinates relative to
           android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
             </td>
 
@@ -15642,7 +15919,8 @@ FREEFORM cropping.<wbr/> LEGACY capability devices will only support CENTER_<wbr
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>The crop region coordinate system is based off
+              <p>This control can be used to implement digital zoom.<wbr/></p>
+<p>The crop region coordinate system is based off
 <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>,<wbr/> with <code>(0,<wbr/> 0)</code> being the
 top-left corner of the sensor active array.<wbr/></p>
 <p>Output streams use this rectangle to produce their output,<wbr/>
@@ -15751,7 +16029,7 @@ light.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              nanoseconds
+              Nanoseconds
             </td>
 
             <td class="entry_range">
@@ -15770,8 +16048,11 @@ light.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If the sensor can't expose this exact duration,<wbr/> it should shorten the
-duration exposed to the nearest possible value (rather than expose longer).<wbr/></p>
+              <p>If the sensor can't expose this exact duration,<wbr/> it will shorten the
+duration exposed to the nearest possible value (rather than expose longer).<wbr/>
+The final exposure time used will be available in the output capture result.<wbr/></p>
+<p>This control is only effective if <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> or <a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> is set to
+OFF; otherwise the auto-exposure algorithm will override this value.<wbr/></p>
             </td>
           </tr>
 
@@ -15804,7 +16085,7 @@ start of next frame exposure.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              nanoseconds
+              Nanoseconds
             </td>
 
             <td class="entry_range">
@@ -15894,6 +16175,8 @@ if all buffers from the previous <code>Rstall</code> have already been
 delivered.<wbr/></p>
 <p>For more details about stalling,<wbr/> see
 StreamConfigurationMap#getOutputStallDuration(int,<wbr/>Size).<wbr/></p>
+<p>This control is only effective if <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> or <a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> is set to
+OFF; otherwise the auto-exposure algorithm will override this value.<wbr/></p>
             </td>
           </tr>
 
@@ -16009,9 +16292,6 @@ when <a href="#controls_android.sensor.testPatternMode">android.<wbr/>sensor.<wb
             </td>
 
             <td class="entry_range">
-              <p>Optional.<wbr/>
-Must be supported if <a href="#static_android.sensor.availableTestPatternModes">android.<wbr/>sensor.<wbr/>available<wbr/>Test<wbr/>Pattern<wbr/>Modes</a> contains
-SOLID_<wbr/>COLOR.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -16162,8 +16442,7 @@ doing a real exposure from the camera.<wbr/></p>
             </td>
 
             <td class="entry_range">
-              <p>Optional.<wbr/> Defaults to OFF.<wbr/> Value must be one of
-<a href="#static_android.sensor.availableTestPatternModes">android.<wbr/>sensor.<wbr/>available<wbr/>Test<wbr/>Pattern<wbr/>Modes</a></p>
+              <p><a href="#static_android.sensor.availableTestPatternModes">android.<wbr/>sensor.<wbr/>available<wbr/>Test<wbr/>Pattern<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -16181,6 +16460,7 @@ work as normal.<wbr/></p>
 <p>For example,<wbr/> if manual flash is enabled,<wbr/> flash firing should still
 occur (and that the test pattern remain unmodified,<wbr/> since the flash
 would not actually affect it).<wbr/></p>
+<p>Defaults to OFF.<wbr/></p>
             </td>
           </tr>
 
@@ -16232,7 +16512,7 @@ sensor interconnect bus (such as CSI2) or memory.<wbr/></p>
                 
           <tr class="entry" id="static_android.sensor.info.activeArraySize">
             <td class="entry_name
-             " rowspan="3">
+             " rowspan="5">
               android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size
             </td>
             <td class="entry_type">
@@ -16254,17 +16534,16 @@ sensor interconnect bus (such as CSI2) or memory.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Area of raw data which corresponds to only
+              <p>The area of the image sensor which corresponds to
 active pixels.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Pixel coordinates on the image sensor
             </td>
 
             <td class="entry_range">
-              <p>This array contains <code>(xmin,<wbr/> ymin,<wbr/> width,<wbr/> height)</code>.<wbr/> The <code>(xmin,<wbr/> ymin)</code> must be
-&gt;= <code>(0,<wbr/>0)</code>.<wbr/> The <code>(width,<wbr/> height)</code> must be &lt;=
-<code><a href="#static_android.sensor.info.pixelArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pixel<wbr/>Array<wbr/>Size</a></code>.<wbr/></p>
+              
             </td>
 
             <td class="entry_tags">
@@ -16279,11 +16558,29 @@ active pixels.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>It is smaller or equal to
-sensor full pixel array,<wbr/> which could include the black calibration pixels.<wbr/></p>
+              <p>This is the region of the sensor that actually receives light from the scene.<wbr/>
+Therefore,<wbr/> the size of this region determines the maximum field of view and the maximum
+number of pixels that an image from this sensor can contain.<wbr/></p>
+<p>The rectangle is defined in terms of the full pixel array; (0,<wbr/>0) is the top-left of the
+full pixel array,<wbr/> and the size of the full pixel array is given by
+<a href="#static_android.sensor.info.pixelArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pixel<wbr/>Array<wbr/>Size</a>.<wbr/></p>
+<p>Most other keys listing pixel coordinates have their coordinate systems based on the
+active array,<wbr/> with <code>(0,<wbr/> 0)</code> being the top-left of the active array rectangle.<wbr/></p>
+<p>The active array may be smaller than the full pixel array,<wbr/> since the full array may
+include black calibration pixels or other inactive regions.<wbr/></p>
             </td>
           </tr>
 
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">HAL Implementation Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>This array contains <code>(xmin,<wbr/> ymin,<wbr/> width,<wbr/> height)</code>.<wbr/> The <code>(xmin,<wbr/> ymin)</code> must be
+&gt;= <code>(0,<wbr/>0)</code>.<wbr/>
+The <code>(width,<wbr/> height)</code> must be &lt;= <code><a href="#static_android.sensor.info.pixelArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>pixel<wbr/>Array<wbr/>Size</a></code>.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
            <!-- end of entry -->
@@ -16313,7 +16610,8 @@ sensor full pixel array,<wbr/> which could include the black calibration pixels.
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Range of valid sensitivities.<wbr/></p>
+              <p>Range of sensitivities for <a href="#controls_android.sensor.sensitivity">android.<wbr/>sensor.<wbr/>sensitivity</a> supported by this
+camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -16336,9 +16634,7 @@ sensor full pixel array,<wbr/> which could include the black calibration pixels.
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>The minimum and maximum valid values for the
-<a href="#controls_android.sensor.sensitivity">android.<wbr/>sensor.<wbr/>sensitivity</a> control.<wbr/></p>
-<p>The values are the standard ISO sensitivity values,<wbr/>
+              <p>The values are the standard ISO sensitivity values,<wbr/>
 as defined in ISO 12232:2006.<wbr/></p>
             </td>
           </tr>
@@ -16413,7 +16709,7 @@ the sensor,<wbr/> in reading order.<wbr/></p>
                 
           <tr class="entry" id="static_android.sensor.info.exposureTimeRange">
             <td class="entry_name
-             " rowspan="5">
+             " rowspan="3">
               android.<wbr/>sensor.<wbr/>info.<wbr/>exposure<wbr/>Time<wbr/>Range
             </td>
             <td class="entry_type">
@@ -16435,17 +16731,18 @@ the sensor,<wbr/> in reading order.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Range of valid exposure
-times used by <a href="#controls_android.sensor.exposureTime">android.<wbr/>sensor.<wbr/>exposure<wbr/>Time</a>.<wbr/></p>
+              <p>The range of image exposure times for <a href="#controls_android.sensor.exposureTime">android.<wbr/>sensor.<wbr/>exposure<wbr/>Time</a> supported
+by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Nanoseconds
             </td>
 
             <td class="entry_range">
-              <p>Min &lt;= 100e3 (100 us).<wbr/> For FULL capability devices
-(<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> == FULL),<wbr/> Max SHOULD be
-&gt;= 1e9 (1sec),<wbr/> MUST be &gt;= 100e6 (100ms)</p>
+              <p>The minimum exposure time will be less than 100 us.<wbr/> For FULL
+capability devices (<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> == FULL),<wbr/>
+the maximum exposure time will be greater than 100ms.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -16455,16 +16752,6 @@ times used by <a href="#controls_android.sensor.exposureTime">android.<wbr/>sens
             </td>
 
           </tr>
-          <tr class="entries_header">
-            <th class="th_details" colspan="5">Details</th>
-          </tr>
-          <tr class="entry_cont">
-            <td class="entry_details" colspan="5">
-              <p>The min value will be &lt;= 100e3 (100 us).<wbr/> For FULL
-capability devices (<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> == FULL),<wbr/>
-max will be &gt;= 100e6 (100ms)</p>
-            </td>
-          </tr>
 
           <tr class="entries_header">
             <th class="th_details" colspan="5">HAL Implementation Details</th>
@@ -16472,8 +16759,8 @@ max will be &gt;= 100e6 (100ms)</p>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
               <p>For FULL capability devices (<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> == FULL),<wbr/>
-The maximum of the range SHOULD be at least
-1 second (1e9),<wbr/> MUST be at least 100ms.<wbr/></p>
+The maximum of the range SHOULD be at least 1 second (1e9),<wbr/> MUST be at least
+100ms.<wbr/></p>
             </td>
           </tr>
 
@@ -16500,18 +16787,17 @@ The maximum of the range SHOULD be at least
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Maximum possible frame duration (minimum frame
-rate).<wbr/></p>
+              <p>The maximum possible frame duration (minimum frame rate) for
+<a href="#controls_android.sensor.frameDuration">android.<wbr/>sensor.<wbr/>frame<wbr/>Duration</a> that is supported this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              nanoseconds
+              Nanoseconds
             </td>
 
             <td class="entry_range">
               <p>For FULL capability devices
-(<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> == FULL),<wbr/> Max SHOULD be
-&gt;= 1e9 (1sec),<wbr/> MUST be &gt;= 100e6 (100ms)</p>
+(<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> == FULL),<wbr/> at least 100ms.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -16526,16 +16812,11 @@ rate).<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>The largest possible <a href="#controls_android.sensor.frameDuration">android.<wbr/>sensor.<wbr/>frame<wbr/>Duration</a>
-that will be accepted by the camera device.<wbr/> Attempting to use
-frame durations beyond the maximum will result in the frame duration
-being clipped to the maximum.<wbr/> See that control
-for a full definition of frame durations.<wbr/></p>
-<p>Refer to
-StreamConfigurationMap#getOutputMinFrameDuration(int,<wbr/>Size)
-for the minimum frame duration values.<wbr/></p>
-<p>For FULL capability devices (<a href="#static_android.info.supportedHardwareLevel">android.<wbr/>info.<wbr/>supported<wbr/>Hardware<wbr/>Level</a> == FULL),<wbr/>
-max will be &gt;= 100e6 (100ms).<wbr/></p>
+              <p>Attempting to use frame durations beyond the maximum will result in the frame
+duration being clipped to the maximum.<wbr/> See that control for a full definition of frame
+durations.<wbr/></p>
+<p>Refer to StreamConfigurationMap#getOutputMinFrameDuration(int,<wbr/>Size) for the minimum
+frame duration values.<wbr/></p>
             </td>
           </tr>
 
@@ -16582,7 +16863,7 @@ for details about encoding this scenario.<wbr/></p>
               <span class="entry_type_hwlevel">[legacy] </span>
 
 
-                <div class="entry_type_notes">width x height in millimeters</div>
+                <div class="entry_type_notes">width x height</div>
 
 
             </td> <!-- entry_type -->
@@ -16593,6 +16874,7 @@ array.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Millimeters
             </td>
 
             <td class="entry_range">
@@ -16652,11 +16934,12 @@ array defined by <a href="#static_android.sensor.info.pixelArraySize">android.<w
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Dimensions of full pixel array,<wbr/> possibly
+              <p>Dimensions of the full pixel array,<wbr/> possibly
 including black calibration pixels.<wbr/></p>
             </td>
 
             <td class="entry_units">
+              Pixels
             </td>
 
             <td class="entry_range">
@@ -16682,6 +16965,9 @@ or <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<w
 raw size listed in <a href="#static_android.scaler.streamConfigurationMap">android.<wbr/>scaler.<wbr/>stream<wbr/>Configuration<wbr/>Map</a>.<wbr/>
 If a size corresponding to pixelArraySize is listed,<wbr/> the resulting
 raw sensor image will include black pixels.<wbr/></p>
+<p>Some parts of the full pixel array may not receive light from the scene,<wbr/>
+or are otherwise inactive.<wbr/>  The <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a> key
+defines the rectangle of active pixels that actually forms an image.<wbr/></p>
             </td>
           </tr>
 
@@ -16734,7 +17020,7 @@ raw sensor image will include black pixels.<wbr/></p>
 sample values from the sensor.<wbr/>  This is typically caused by the
 sensor becoming highly non-linear or clipping.<wbr/> The minimum for
 each channel is specified by the offset in the
-<a href="#static_android.sensor.blackLevelPattern">android.<wbr/>sensor.<wbr/>black<wbr/>Level<wbr/>Pattern</a> tag.<wbr/></p>
+<a href="#static_android.sensor.blackLevelPattern">android.<wbr/>sensor.<wbr/>black<wbr/>Level<wbr/>Pattern</a> key.<wbr/></p>
 <p>The white level is typically determined either by sensor bit depth
 (8-14 bits is expected),<wbr/> or by the point where the sensor response
 becomes too non-linear to be useful.<wbr/>  The default value for this is
@@ -16954,10 +17240,10 @@ calculating the <a href="#static_android.sensor.colorTransform1">android.<wbr/>s
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>The values in this tag correspond to the values defined for the
+              <p>The values in this key correspond to the values defined for the
 EXIF LightSource tag.<wbr/> These illuminants are standard light sources
 that are often used calibrating camera devices.<wbr/></p>
-<p>If this tag is present,<wbr/> then <a href="#static_android.sensor.colorTransform1">android.<wbr/>sensor.<wbr/>color<wbr/>Transform1</a>,<wbr/>
+<p>If this key is present,<wbr/> then <a href="#static_android.sensor.colorTransform1">android.<wbr/>sensor.<wbr/>color<wbr/>Transform1</a>,<wbr/>
 <a href="#static_android.sensor.calibrationTransform1">android.<wbr/>sensor.<wbr/>calibration<wbr/>Transform1</a>,<wbr/> and
 <a href="#static_android.sensor.forwardMatrix1">android.<wbr/>sensor.<wbr/>forward<wbr/>Matrix1</a> will also be present.<wbr/></p>
 <p>Some devices may choose to provide a second set of calibration
@@ -17024,6 +17310,7 @@ calculating the <a href="#static_android.sensor.colorTransform2">android.<wbr/>s
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#static_android.sensor.referenceIlluminant1">android.<wbr/>sensor.<wbr/>reference<wbr/>Illuminant1</a></p>
             </td>
 
             <td class="entry_tags">
@@ -17038,10 +17325,8 @@ calculating the <a href="#static_android.sensor.colorTransform2">android.<wbr/>s
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>See <a href="#static_android.sensor.referenceIlluminant1">android.<wbr/>sensor.<wbr/>reference<wbr/>Illuminant1</a> for more details.<wbr/>
-Valid values for this are the same as those given for the first
-reference illuminant.<wbr/></p>
-<p>If this tag is present,<wbr/> then <a href="#static_android.sensor.colorTransform2">android.<wbr/>sensor.<wbr/>color<wbr/>Transform2</a>,<wbr/>
+              <p>See <a href="#static_android.sensor.referenceIlluminant1">android.<wbr/>sensor.<wbr/>reference<wbr/>Illuminant1</a> for more details.<wbr/></p>
+<p>If this key is present,<wbr/> then <a href="#static_android.sensor.colorTransform2">android.<wbr/>sensor.<wbr/>color<wbr/>Transform2</a>,<wbr/>
 <a href="#static_android.sensor.calibrationTransform2">android.<wbr/>sensor.<wbr/>calibration<wbr/>Transform2</a>,<wbr/> and
 <a href="#static_android.sensor.forwardMatrix2">android.<wbr/>sensor.<wbr/>forward<wbr/>Matrix2</a> will also be present.<wbr/></p>
             </td>
@@ -17524,11 +17809,11 @@ ISO=100</p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This tag specifies the zero light value for each of the CFA mosaic
+              <p>This key specifies the zero light value for each of the CFA mosaic
 channels in the camera sensor.<wbr/>  The maximal value output by the
 sensor is represented by the value in <a href="#static_android.sensor.info.whiteLevel">android.<wbr/>sensor.<wbr/>info.<wbr/>white<wbr/>Level</a>.<wbr/></p>
 <p>The values are given in the same order as channels listed for the CFA
-layout tag (see <a href="#static_android.sensor.info.colorFilterArrangement">android.<wbr/>sensor.<wbr/>info.<wbr/>color<wbr/>Filter<wbr/>Arrangement</a>),<wbr/> i.<wbr/>e.<wbr/> the
+layout key (see <a href="#static_android.sensor.info.colorFilterArrangement">android.<wbr/>sensor.<wbr/>info.<wbr/>color<wbr/>Filter<wbr/>Arrangement</a>),<wbr/> i.<wbr/>e.<wbr/> the
 nth value given corresponds to the black level offset for the nth
 color channel listed in the CFA.<wbr/></p>
             </td>
@@ -17604,7 +17889,7 @@ digital.<wbr/></p>
                 
           <tr class="entry" id="static_android.sensor.orientation">
             <td class="entry_name
-             " rowspan="1">
+             " rowspan="3">
               android.<wbr/>sensor.<wbr/>orientation
             </td>
             <td class="entry_type">
@@ -17621,20 +17906,17 @@ digital.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Clockwise angle through which the output
-image needs to be rotated to be upright on the device
-screen in its native orientation.<wbr/> Also defines the
-direction of rolling shutter readout,<wbr/> which is from top
-to bottom in the sensor's coordinate system</p>
+              <p>Clockwise angle through which the output image needs to be rotated to be
+upright on the device screen in its native orientation.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              degrees clockwise rotation,<wbr/> only multiples of
+              Degrees of clockwise rotation; always a multiple of
           90
             </td>
 
             <td class="entry_range">
-              <p>0,<wbr/>90,<wbr/>180,<wbr/>270</p>
+              <p>0,<wbr/> 90,<wbr/> 180,<wbr/> 270</p>
             </td>
 
             <td class="entry_tags">
@@ -17644,6 +17926,15 @@ to bottom in the sensor's coordinate system</p>
             </td>
 
           </tr>
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>Also defines the direction of rolling shutter readout,<wbr/> which is from top to bottom in
+the sensor's coordinate system.<wbr/></p>
+            </td>
+          </tr>
 
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
@@ -17712,7 +18003,7 @@ element.<wbr/></p>
                 
           <tr class="entry" id="static_android.sensor.availableTestPatternModes">
             <td class="entry_name
-             " rowspan="3">
+             " rowspan="5">
               android.<wbr/>sensor.<wbr/>available<wbr/>Test<wbr/>Pattern<wbr/>Modes
             </td>
             <td class="entry_type">
@@ -17733,14 +18024,15 @@ element.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Lists the supported sensor test pattern modes for <a href="#controls_android.sensor.testPatternMode">android.<wbr/>sensor.<wbr/>test<wbr/>Pattern<wbr/>Mode</a>.<wbr/></p>
+              <p>List of sensor test pattern modes for <a href="#controls_android.sensor.testPatternMode">android.<wbr/>sensor.<wbr/>test<wbr/>Pattern<wbr/>Mode</a>
+supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
-              <p>Always includes OFF if defined.<wbr/> All custom modes must be &gt;= CUSTOM1</p>
+              <p>Any value listed in <a href="#controls_android.sensor.testPatternMode">android.<wbr/>sensor.<wbr/>test<wbr/>Pattern<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -17752,10 +18044,18 @@ element.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Optional.<wbr/> Defaults to [OFF].<wbr/></p>
+              <p>Defaults to OFF,<wbr/> and always includes OFF if defined.<wbr/></p>
             </td>
           </tr>
 
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">HAL Implementation Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>All custom modes must be &gt;= CUSTOM1.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
            <!-- end of entry -->
@@ -17812,7 +18112,7 @@ light.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              nanoseconds
+              Nanoseconds
             </td>
 
             <td class="entry_range">
@@ -17831,8 +18131,11 @@ light.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If the sensor can't expose this exact duration,<wbr/> it should shorten the
-duration exposed to the nearest possible value (rather than expose longer).<wbr/></p>
+              <p>If the sensor can't expose this exact duration,<wbr/> it will shorten the
+duration exposed to the nearest possible value (rather than expose longer).<wbr/>
+The final exposure time used will be available in the output capture result.<wbr/></p>
+<p>This control is only effective if <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> or <a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> is set to
+OFF; otherwise the auto-exposure algorithm will override this value.<wbr/></p>
             </td>
           </tr>
 
@@ -17865,7 +18168,7 @@ start of next frame exposure.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              nanoseconds
+              Nanoseconds
             </td>
 
             <td class="entry_range">
@@ -17955,6 +18258,8 @@ if all buffers from the previous <code>Rstall</code> have already been
 delivered.<wbr/></p>
 <p>For more details about stalling,<wbr/> see
 StreamConfigurationMap#getOutputStallDuration(int,<wbr/>Size).<wbr/></p>
+<p>This control is only effective if <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> or <a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> is set to
+OFF; otherwise the auto-exposure algorithm will override this value.<wbr/></p>
             </td>
           </tr>
 
@@ -18064,7 +18369,7 @@ row of the image sensor active array,<wbr/> in nanoseconds.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              nanoseconds
+              Nanoseconds
             </td>
 
             <td class="entry_range">
@@ -18144,7 +18449,7 @@ somewhere close to it.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              celsius
+              Celsius
             </td>
 
             <td class="entry_range">
@@ -18266,10 +18571,10 @@ processing raw sensor data.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This tag contains two noise model coefficients for each CFA channel
+              <p>This key contains two noise model coefficients for each CFA channel
 corresponding to the sensor amplification (S) and sensor readout
 noise (O).<wbr/>  These are given as pairs of coefficients for each channel
-in the same order as channels listed for the CFA layout tag
+in the same order as channels listed for the CFA layout key
 (see <a href="#static_android.sensor.info.colorFilterArrangement">android.<wbr/>sensor.<wbr/>info.<wbr/>color<wbr/>Filter<wbr/>Arrangement</a>).<wbr/>  This is
 represented as an array of Pair&lt;Double,<wbr/> Double&gt;,<wbr/> where
 the first member of the Pair at index n is the S coefficient and the
@@ -18331,8 +18636,8 @@ for each pixel.<wbr/></p>
 
             <td class="entry_units">
               
-          Hue shift is given in degrees; saturation and value scale factors are
-          unitless.<wbr/>
+          The hue shift is given in degrees; saturation and value scale factors are
+          unitless and are between 0 and 1 inclusive
           
             </td>
 
@@ -18355,7 +18660,7 @@ for each pixel.<wbr/></p>
 <a href="#static_android.sensor.profileHueSatMapDimensions">android.<wbr/>sensor.<wbr/>profile<wbr/>Hue<wbr/>Sat<wbr/>Map<wbr/>Dimensions</a>.<wbr/></p>
 <p>Each entry of this map contains three floats corresponding to the
 hue shift,<wbr/> saturation scale,<wbr/> and value scale,<wbr/> respectively; where the
-hue shift has the lowest index.<wbr/> The map entries are stored in the tag
+hue shift has the lowest index.<wbr/> The map entries are stored in the key
 in nested loop order,<wbr/> with the value divisions in the outer loop,<wbr/> the
 hue divisions in the middle loop,<wbr/> and the saturation divisions in the
 inner loop.<wbr/> All zero input saturation entries are required to have a
@@ -18415,7 +18720,7 @@ sample is required to be <code>(1,<wbr/> 1)</code>.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This tag contains a default tone curve that can be applied while
+              <p>This key contains a default tone curve that can be applied while
 processing the image as a starting point for user adjustments.<wbr/>
 The curve is specified as a list of value pairs in linear gamma.<wbr/>
 The curve is interpolated using a cubic spline.<wbr/></p>
@@ -18547,9 +18852,6 @@ when <a href="#controls_android.sensor.testPatternMode">android.<wbr/>sensor.<wb
             </td>
 
             <td class="entry_range">
-              <p>Optional.<wbr/>
-Must be supported if <a href="#static_android.sensor.availableTestPatternModes">android.<wbr/>sensor.<wbr/>available<wbr/>Test<wbr/>Pattern<wbr/>Modes</a> contains
-SOLID_<wbr/>COLOR.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -18700,8 +19002,7 @@ doing a real exposure from the camera.<wbr/></p>
             </td>
 
             <td class="entry_range">
-              <p>Optional.<wbr/> Defaults to OFF.<wbr/> Value must be one of
-<a href="#static_android.sensor.availableTestPatternModes">android.<wbr/>sensor.<wbr/>available<wbr/>Test<wbr/>Pattern<wbr/>Modes</a></p>
+              <p><a href="#static_android.sensor.availableTestPatternModes">android.<wbr/>sensor.<wbr/>available<wbr/>Test<wbr/>Pattern<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -18719,6 +19020,7 @@ work as normal.<wbr/></p>
 <p>For example,<wbr/> if manual flash is enabled,<wbr/> flash firing should still
 occur (and that the test pattern remain unmodified,<wbr/> since the flash
 would not actually affect it).<wbr/></p>
+<p>Defaults to OFF.<wbr/></p>
             </td>
           </tr>
 
@@ -18763,7 +19065,7 @@ and the start of last row exposure.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              nanoseconds
+              Nanoseconds
             </td>
 
             <td class="entry_range">
@@ -18783,9 +19085,10 @@ StreamConfigurationMap#getOutputMinFrameDuration(int,<wbr/> Size).<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This is the exposure time skew (in the unit of nanosecond) between the first and
-last row exposure start times.<wbr/> The first row and the last row are the first
-and last rows inside of the <a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/></p>
+              <p>This is the exposure time skew between the first and last
+row exposure start times.<wbr/> The first row and the last row are
+the first and last rows inside of the
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/></p>
 <p>For typical camera sensors that use rolling shutters,<wbr/> this is also equivalent
 to the frame readout time.<wbr/></p>
             </td>
@@ -18894,27 +19197,26 @@ to the image data.<wbr/></p>
               <p>When set to OFF mode,<wbr/> no lens shading correction will be applied by the
 camera device,<wbr/> and an identity lens shading map data will be provided
 if <code><a href="#controls_android.statistics.lensShadingMapMode">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map<wbr/>Mode</a> == ON</code>.<wbr/> For example,<wbr/> for lens
-shading map with size specified as <code><a href="#static_android.lens.info.shadingMapSize">android.<wbr/>lens.<wbr/>info.<wbr/>shading<wbr/>Map<wbr/>Size</a> = [ 4,<wbr/> 3 ]</code>,<wbr/>
-the output <a href="#dynamic_android.statistics.lensShadingMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map</a> for this case will be an identity map
-shown below:</p>
+shading map with size of <code>[ 4,<wbr/> 3 ]</code>,<wbr/>
+the output <a href="#dynamic_android.statistics.lensShadingCorrectionMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Correction<wbr/>Map</a> for this case will be an identity
+map shown below:</p>
 <pre><code>[ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-    1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-    1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>   1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-    1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0 ]
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0 ]
 </code></pre>
-<p>When set to other modes,<wbr/> lens shading correction will be applied by the
-camera device.<wbr/> Applications can request lens shading map data by setting
-<a href="#controls_android.statistics.lensShadingMapMode">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map<wbr/>Mode</a> to ON,<wbr/> and then the camera device will provide
-lens shading map data in <a href="#dynamic_android.statistics.lensShadingMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map</a>,<wbr/> with size specified
-by <a href="#static_android.lens.info.shadingMapSize">android.<wbr/>lens.<wbr/>info.<wbr/>shading<wbr/>Map<wbr/>Size</a>; the returned shading map data will be the one
-applied by the camera device for this capture request.<wbr/></p>
-<p>The shading map data may depend on the auto-exposure (AE) and AWB statistics,<wbr/> therefore the reliability
-of the map data may be affected by the AE and AWB algorithms.<wbr/> When AE and AWB are in
-AUTO modes(<a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> <code>!=</code> OFF and <a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a> <code>!=</code> OFF),<wbr/>
-to get best results,<wbr/> it is recommended that the applications wait for the AE and AWB to
-be converged before using the returned shading map data.<wbr/></p>
+<p>When set to other modes,<wbr/> lens shading correction will be applied by the camera
+device.<wbr/> Applications can request lens shading map data by setting
+<a href="#controls_android.statistics.lensShadingMapMode">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map<wbr/>Mode</a> to ON,<wbr/> and then the camera device will provide lens
+shading map data in <a href="#dynamic_android.statistics.lensShadingCorrectionMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Correction<wbr/>Map</a>; the returned shading map
+data will be the one applied by the camera device for this capture request.<wbr/></p>
+<p>The shading map data may depend on the auto-exposure (AE) and AWB statistics,<wbr/> therefore
+the reliability of the map data may be affected by the AE and AWB algorithms.<wbr/> When AE and
+AWB are in AUTO modes(<a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> <code>!=</code> OFF and <a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a> <code>!=</code>
+OFF),<wbr/> to get best results,<wbr/> it is recommended that the applications wait for the AE and AWB
+to be converged before using the returned shading map data.<wbr/></p>
             </td>
           </tr>
 
@@ -19050,27 +19352,26 @@ to the image data.<wbr/></p>
               <p>When set to OFF mode,<wbr/> no lens shading correction will be applied by the
 camera device,<wbr/> and an identity lens shading map data will be provided
 if <code><a href="#controls_android.statistics.lensShadingMapMode">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map<wbr/>Mode</a> == ON</code>.<wbr/> For example,<wbr/> for lens
-shading map with size specified as <code><a href="#static_android.lens.info.shadingMapSize">android.<wbr/>lens.<wbr/>info.<wbr/>shading<wbr/>Map<wbr/>Size</a> = [ 4,<wbr/> 3 ]</code>,<wbr/>
-the output <a href="#dynamic_android.statistics.lensShadingMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map</a> for this case will be an identity map
-shown below:</p>
+shading map with size of <code>[ 4,<wbr/> 3 ]</code>,<wbr/>
+the output <a href="#dynamic_android.statistics.lensShadingCorrectionMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Correction<wbr/>Map</a> for this case will be an identity
+map shown below:</p>
 <pre><code>[ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-    1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-    1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>   1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
-    1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0 ]
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>
+ 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/>  1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0,<wbr/> 1.<wbr/>0 ]
 </code></pre>
-<p>When set to other modes,<wbr/> lens shading correction will be applied by the
-camera device.<wbr/> Applications can request lens shading map data by setting
-<a href="#controls_android.statistics.lensShadingMapMode">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map<wbr/>Mode</a> to ON,<wbr/> and then the camera device will provide
-lens shading map data in <a href="#dynamic_android.statistics.lensShadingMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map</a>,<wbr/> with size specified
-by <a href="#static_android.lens.info.shadingMapSize">android.<wbr/>lens.<wbr/>info.<wbr/>shading<wbr/>Map<wbr/>Size</a>; the returned shading map data will be the one
-applied by the camera device for this capture request.<wbr/></p>
-<p>The shading map data may depend on the auto-exposure (AE) and AWB statistics,<wbr/> therefore the reliability
-of the map data may be affected by the AE and AWB algorithms.<wbr/> When AE and AWB are in
-AUTO modes(<a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> <code>!=</code> OFF and <a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a> <code>!=</code> OFF),<wbr/>
-to get best results,<wbr/> it is recommended that the applications wait for the AE and AWB to
-be converged before using the returned shading map data.<wbr/></p>
+<p>When set to other modes,<wbr/> lens shading correction will be applied by the camera
+device.<wbr/> Applications can request lens shading map data by setting
+<a href="#controls_android.statistics.lensShadingMapMode">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map<wbr/>Mode</a> to ON,<wbr/> and then the camera device will provide lens
+shading map data in <a href="#dynamic_android.statistics.lensShadingCorrectionMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Correction<wbr/>Map</a>; the returned shading map
+data will be the one applied by the camera device for this capture request.<wbr/></p>
+<p>The shading map data may depend on the auto-exposure (AE) and AWB statistics,<wbr/> therefore
+the reliability of the map data may be affected by the AE and AWB algorithms.<wbr/> When AE and
+AWB are in AUTO modes(<a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a> <code>!=</code> OFF and <a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a> <code>!=</code>
+OFF),<wbr/> to get best results,<wbr/> it is recommended that the applications wait for the AE and AWB
+to be converged before using the returned shading map data.<wbr/></p>
             </td>
           </tr>
 
@@ -19113,7 +19414,7 @@ be converged before using the returned shading map data.<wbr/></p>
                 
           <tr class="entry" id="controls_android.statistics.faceDetectMode">
             <td class="entry_name
-             " rowspan="3">
+             " rowspan="5">
               android.<wbr/>statistics.<wbr/>face<wbr/>Detect<wbr/>Mode
             </td>
             <td class="entry_type">
@@ -19135,27 +19436,21 @@ results.<wbr/></p></span>
                   <li>
                     <span class="entry_type_enum_name">SIMPLE</span>
                     <span class="entry_type_enum_optional">[optional]</span>
-                    <span class="entry_type_enum_notes"><p>Return face rectangle and confidence values only.<wbr/></p>
-<p>In this mode,<wbr/> only <a href="#dynamic_android.statistics.faceRectangles">android.<wbr/>statistics.<wbr/>face<wbr/>Rectangles</a> and
-<a href="#dynamic_android.statistics.faceScores">android.<wbr/>statistics.<wbr/>face<wbr/>Scores</a> outputs are valid.<wbr/></p></span>
+                    <span class="entry_type_enum_notes"><p>Return face rectangle and confidence values only.<wbr/></p></span>
                   </li>
                   <li>
                     <span class="entry_type_enum_name">FULL</span>
                     <span class="entry_type_enum_optional">[optional]</span>
                     <span class="entry_type_enum_notes"><p>Return all face
 metadata.<wbr/></p>
-<p>In this mode,<wbr/>
-<a href="#dynamic_android.statistics.faceRectangles">android.<wbr/>statistics.<wbr/>face<wbr/>Rectangles</a>,<wbr/>
-<a href="#dynamic_android.statistics.faceScores">android.<wbr/>statistics.<wbr/>face<wbr/>Scores</a>,<wbr/>
-<a href="#dynamic_android.statistics.faceIds">android.<wbr/>statistics.<wbr/>face<wbr/>Ids</a>,<wbr/> and
-<a href="#dynamic_android.statistics.faceLandmarks">android.<wbr/>statistics.<wbr/>face<wbr/>Landmarks</a> outputs are valid.<wbr/></p></span>
+<p>In this mode,<wbr/> face rectangles,<wbr/> scores,<wbr/> landmarks,<wbr/> and face IDs are all valid.<wbr/></p></span>
                   </li>
                 </ul>
 
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Control for the face detector
+              <p>Operating mode for the face detector
 unit.<wbr/></p>
             </td>
 
@@ -19180,11 +19475,21 @@ unit.<wbr/></p>
             <td class="entry_details" colspan="5">
               <p>Whether face detection is enabled,<wbr/> and whether it
 should output just the basic fields or the full set of
-fields.<wbr/> Value must be one of the
-<a href="#static_android.statistics.info.availableFaceDetectModes">android.<wbr/>statistics.<wbr/>info.<wbr/>available<wbr/>Face<wbr/>Detect<wbr/>Modes</a>.<wbr/></p>
+fields.<wbr/></p>
             </td>
           </tr>
 
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">HAL Implementation Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>SIMPLE mode must fill in <a href="#dynamic_android.statistics.faceRectangles">android.<wbr/>statistics.<wbr/>face<wbr/>Rectangles</a> and
+<a href="#dynamic_android.statistics.faceScores">android.<wbr/>statistics.<wbr/>face<wbr/>Scores</a>.<wbr/>
+FULL mode must also fill in <a href="#dynamic_android.statistics.faceIds">android.<wbr/>statistics.<wbr/>face<wbr/>Ids</a>,<wbr/> and
+<a href="#dynamic_android.statistics.faceLandmarks">android.<wbr/>statistics.<wbr/>face<wbr/>Landmarks</a>.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
            <!-- end of entry -->
@@ -19316,13 +19621,14 @@ generation</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Operating mode for hotpixel map generation.<wbr/></p>
+              <p>Operating mode for hot pixel map generation.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.statistics.info.availableHotPixelMapModes">android.<wbr/>statistics.<wbr/>info.<wbr/>available<wbr/>Hot<wbr/>Pixel<wbr/>Map<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -19338,9 +19644,8 @@ generation</p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If set to ON,<wbr/> a hotpixel map is returned in <a href="#dynamic_android.statistics.hotPixelMap">android.<wbr/>statistics.<wbr/>hot<wbr/>Pixel<wbr/>Map</a>.<wbr/>
-If set to OFF,<wbr/> no hotpixel map will be returned.<wbr/></p>
-<p>This must be set to a valid mode from <a href="#static_android.statistics.info.availableHotPixelMapModes">android.<wbr/>statistics.<wbr/>info.<wbr/>available<wbr/>Hot<wbr/>Pixel<wbr/>Map<wbr/>Modes</a>.<wbr/></p>
+              <p>If set to <code>true</code>,<wbr/> a hot pixel map is returned in <a href="#dynamic_android.statistics.hotPixelMap">android.<wbr/>statistics.<wbr/>hot<wbr/>Pixel<wbr/>Map</a>.<wbr/>
+If set to <code>false</code>,<wbr/> no hot pixel map will be returned.<wbr/></p>
             </td>
           </tr>
 
@@ -19403,7 +19708,7 @@ shading map in output result metadata.<wbr/></p>
               <p>When set to ON,<wbr/>
 <a href="#dynamic_android.statistics.lensShadingMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map</a> will be provided in
 the output result metadata.<wbr/></p>
-<p>Required for devices with the RAW capability.<wbr/></p>
+<p>ON is always supported on devices with the RAW capability.<wbr/></p>
             </td>
           </tr>
 
@@ -19465,18 +19770,15 @@ the output result metadata.<wbr/></p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The face detection modes that are available
-for this camera device.<wbr/></p>
+              <p>List of face detection modes for <a href="#controls_android.statistics.faceDetectMode">android.<wbr/>statistics.<wbr/>face<wbr/>Detect<wbr/>Mode</a> that are
+supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              List of enum:
-            OFF
-            SIMPLE
-            FULL
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.statistics.faceDetectMode">android.<wbr/>statistics.<wbr/>face<wbr/>Detect<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -19489,12 +19791,6 @@ for this camera device.<wbr/></p>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
               <p>OFF is always supported.<wbr/></p>
-<p>SIMPLE means the device supports the
-<a href="#dynamic_android.statistics.faceRectangles">android.<wbr/>statistics.<wbr/>face<wbr/>Rectangles</a> and
-<a href="#dynamic_android.statistics.faceScores">android.<wbr/>statistics.<wbr/>face<wbr/>Scores</a> outputs.<wbr/></p>
-<p>FULL means the device additionally supports the
-<a href="#dynamic_android.statistics.faceIds">android.<wbr/>statistics.<wbr/>face<wbr/>Ids</a> and
-<a href="#dynamic_android.statistics.faceLandmarks">android.<wbr/>statistics.<wbr/>face<wbr/>Landmarks</a> outputs.<wbr/></p>
             </td>
           </tr>
 
@@ -19742,13 +20038,15 @@ map</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The set of hot pixel map output modes supported by this camera device.<wbr/></p>
+              <p>List of hot pixel map output modes for <a href="#controls_android.statistics.hotPixelMapMode">android.<wbr/>statistics.<wbr/>hot<wbr/>Pixel<wbr/>Map<wbr/>Mode</a> that are
+supported by this camera device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.statistics.hotPixelMapMode">android.<wbr/>statistics.<wbr/>hot<wbr/>Pixel<wbr/>Map<wbr/>Mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -19764,11 +20062,9 @@ map</p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This tag lists valid output modes for <a href="#controls_android.statistics.hotPixelMapMode">android.<wbr/>statistics.<wbr/>hot<wbr/>Pixel<wbr/>Map<wbr/>Mode</a>.<wbr/></p>
-<p>If no hotpixel map is available for this camera device,<wbr/> this will contain
-only OFF.<wbr/>  If the hotpixel map is available,<wbr/> this will include both
-the ON and OFF options.<wbr/></p>
-<p>Required on devices with the RAW capability.<wbr/></p>
+              <p>If no hotpixel map output is available for this camera device,<wbr/> this will contain only
+<code>false</code>.<wbr/></p>
+<p>ON is always supported on devices with the RAW capability.<wbr/></p>
             </td>
           </tr>
 
@@ -19809,7 +20105,7 @@ the ON and OFF options.<wbr/></p>
                 
           <tr class="entry" id="dynamic_android.statistics.faceDetectMode">
             <td class="entry_name
-             " rowspan="3">
+             " rowspan="5">
               android.<wbr/>statistics.<wbr/>face<wbr/>Detect<wbr/>Mode
             </td>
             <td class="entry_type">
@@ -19831,27 +20127,21 @@ results.<wbr/></p></span>
                   <li>
                     <span class="entry_type_enum_name">SIMPLE</span>
                     <span class="entry_type_enum_optional">[optional]</span>
-                    <span class="entry_type_enum_notes"><p>Return face rectangle and confidence values only.<wbr/></p>
-<p>In this mode,<wbr/> only <a href="#dynamic_android.statistics.faceRectangles">android.<wbr/>statistics.<wbr/>face<wbr/>Rectangles</a> and
-<a href="#dynamic_android.statistics.faceScores">android.<wbr/>statistics.<wbr/>face<wbr/>Scores</a> outputs are valid.<wbr/></p></span>
+                    <span class="entry_type_enum_notes"><p>Return face rectangle and confidence values only.<wbr/></p></span>
                   </li>
                   <li>
                     <span class="entry_type_enum_name">FULL</span>
                     <span class="entry_type_enum_optional">[optional]</span>
                     <span class="entry_type_enum_notes"><p>Return all face
 metadata.<wbr/></p>
-<p>In this mode,<wbr/>
-<a href="#dynamic_android.statistics.faceRectangles">android.<wbr/>statistics.<wbr/>face<wbr/>Rectangles</a>,<wbr/>
-<a href="#dynamic_android.statistics.faceScores">android.<wbr/>statistics.<wbr/>face<wbr/>Scores</a>,<wbr/>
-<a href="#dynamic_android.statistics.faceIds">android.<wbr/>statistics.<wbr/>face<wbr/>Ids</a>,<wbr/> and
-<a href="#dynamic_android.statistics.faceLandmarks">android.<wbr/>statistics.<wbr/>face<wbr/>Landmarks</a> outputs are valid.<wbr/></p></span>
+<p>In this mode,<wbr/> face rectangles,<wbr/> scores,<wbr/> landmarks,<wbr/> and face IDs are all valid.<wbr/></p></span>
                   </li>
                 </ul>
 
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Control for the face detector
+              <p>Operating mode for the face detector
 unit.<wbr/></p>
             </td>
 
@@ -19876,11 +20166,21 @@ unit.<wbr/></p>
             <td class="entry_details" colspan="5">
               <p>Whether face detection is enabled,<wbr/> and whether it
 should output just the basic fields or the full set of
-fields.<wbr/> Value must be one of the
-<a href="#static_android.statistics.info.availableFaceDetectModes">android.<wbr/>statistics.<wbr/>info.<wbr/>available<wbr/>Face<wbr/>Detect<wbr/>Modes</a>.<wbr/></p>
+fields.<wbr/></p>
             </td>
           </tr>
 
+          <tr class="entries_header">
+            <th class="th_details" colspan="5">HAL Implementation Details</th>
+          </tr>
+          <tr class="entry_cont">
+            <td class="entry_details" colspan="5">
+              <p>SIMPLE mode must fill in <a href="#dynamic_android.statistics.faceRectangles">android.<wbr/>statistics.<wbr/>face<wbr/>Rectangles</a> and
+<a href="#dynamic_android.statistics.faceScores">android.<wbr/>statistics.<wbr/>face<wbr/>Scores</a>.<wbr/>
+FULL mode must also fill in <a href="#dynamic_android.statistics.faceIds">android.<wbr/>statistics.<wbr/>face<wbr/>Ids</a>,<wbr/> and
+<a href="#dynamic_android.statistics.faceLandmarks">android.<wbr/>statistics.<wbr/>face<wbr/>Landmarks</a>.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
            <!-- end of entry -->
@@ -20145,7 +20445,7 @@ all times is illegal).<wbr/></p>
 
             <td class="entry_description">
               <p>List of the faces detected through camera face detection
-in this result.<wbr/></p>
+in this capture.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -20803,13 +21103,14 @@ into this metadata field.<wbr/> See
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Operating mode for hotpixel map generation.<wbr/></p>
+              <p>Operating mode for hot pixel map generation.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.statistics.info.availableHotPixelMapModes">android.<wbr/>statistics.<wbr/>info.<wbr/>available<wbr/>Hot<wbr/>Pixel<wbr/>Map<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -20825,9 +21126,8 @@ into this metadata field.<wbr/> See
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If set to ON,<wbr/> a hotpixel map is returned in <a href="#dynamic_android.statistics.hotPixelMap">android.<wbr/>statistics.<wbr/>hot<wbr/>Pixel<wbr/>Map</a>.<wbr/>
-If set to OFF,<wbr/> no hotpixel map will be returned.<wbr/></p>
-<p>This must be set to a valid mode from <a href="#static_android.statistics.info.availableHotPixelMapModes">android.<wbr/>statistics.<wbr/>info.<wbr/>available<wbr/>Hot<wbr/>Pixel<wbr/>Map<wbr/>Modes</a>.<wbr/></p>
+              <p>If set to <code>true</code>,<wbr/> a hot pixel map is returned in <a href="#dynamic_android.statistics.hotPixelMap">android.<wbr/>statistics.<wbr/>hot<wbr/>Pixel<wbr/>Map</a>.<wbr/>
+If set to <code>false</code>,<wbr/> no hot pixel map will be returned.<wbr/></p>
             </td>
           </tr>
 
@@ -20966,7 +21266,7 @@ shading map in output result metadata.<wbr/></p>
               <p>When set to ON,<wbr/>
 <a href="#dynamic_android.statistics.lensShadingMap">android.<wbr/>statistics.<wbr/>lens<wbr/>Shading<wbr/>Map</a> will be provided in
 the output result metadata.<wbr/></p>
-<p>Required for devices with the RAW capability.<wbr/></p>
+<p>ON is always supported on devices with the RAW capability.<wbr/></p>
             </td>
           </tr>
 
@@ -21037,11 +21337,9 @@ CONTRAST_<wbr/>CURVE.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              same as android.<wbr/>tonemap.<wbr/>curve<wbr/>Red
             </td>
 
             <td class="entry_range">
-              <p>same as <a href="#controls_android.tonemap.curveRed">android.<wbr/>tonemap.<wbr/>curve<wbr/>Red</a></p>
             </td>
 
             <td class="entry_tags">
@@ -21092,11 +21390,9 @@ CONTRAST_<wbr/>CURVE.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              same as android.<wbr/>tonemap.<wbr/>curve<wbr/>Red
             </td>
 
             <td class="entry_range">
-              <p>same as <a href="#controls_android.tonemap.curveRed">android.<wbr/>tonemap.<wbr/>curve<wbr/>Red</a></p>
             </td>
 
             <td class="entry_tags">
@@ -21167,8 +21463,8 @@ as a floating-point value such that 0 == black and 1 == white.<wbr/></p>
 <pre><code><a href="#controls_android.tonemap.curveRed">android.<wbr/>tonemap.<wbr/>curve<wbr/>Red</a> =
   [ P0in,<wbr/> P0out,<wbr/> P1in,<wbr/> P1out,<wbr/> P2in,<wbr/> P2out,<wbr/> P3in,<wbr/> P3out,<wbr/> ...,<wbr/> PNin,<wbr/> PNout ]
 2 &lt;= N &lt;= <a href="#static_android.tonemap.maxCurvePoints">android.<wbr/>tonemap.<wbr/>max<wbr/>Curve<wbr/>Points</a></code></pre>
-<p>These are sorted in order of increasing <code>Pin</code>; it is always
-guaranteed that input values 0.<wbr/>0 and 1.<wbr/>0 are included in the list to
+<p>These are sorted in order of increasing <code>Pin</code>; it is
+required that input values 0.<wbr/>0 and 1.<wbr/>0 are included in the list to
 define a complete mapping.<wbr/> For input values between control points,<wbr/>
 the camera device must linearly interpolate between the control
 points.<wbr/></p>
@@ -21369,6 +21665,7 @@ the cost of reduced frame rate compared to raw sensor output.<wbr/></p></span>
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.tonemap.availableToneMapModes">android.<wbr/>tonemap.<wbr/>available<wbr/>Tone<wbr/>Map<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -21391,8 +21688,6 @@ are specified by normalized floating-point numbers.<wbr/></p>
 tables,<wbr/> selective chroma enhancement,<wbr/> or other non-linear color
 transforms will be disabled when <a href="#controls_android.tonemap.mode">android.<wbr/>tonemap.<wbr/>mode</a> is
 CONTRAST_<wbr/>CURVE.<wbr/></p>
-<p>This must be set to a valid mode in
-<a href="#static_android.tonemap.availableToneMapModes">android.<wbr/>tonemap.<wbr/>available<wbr/>Tone<wbr/>Map<wbr/>Modes</a>.<wbr/></p>
 <p>When using either FAST or HIGH_<wbr/>QUALITY,<wbr/> the camera device will
 emit its own tonemap curve in <a href="#controls_android.tonemap.curve">android.<wbr/>tonemap.<wbr/>curve</a>.<wbr/>
 These values are always available,<wbr/> and as close as possible to the
@@ -21462,7 +21757,6 @@ tonemap curve that can be used for <a href="#controls_android.tonemap.curve">and
             </td>
 
             <td class="entry_range">
-              <p>&gt;= 64</p>
             </td>
 
             <td class="entry_tags">
@@ -21474,10 +21768,9 @@ tonemap curve that can be used for <a href="#controls_android.tonemap.curve">and
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>If the actual number of points provided by the application (in
-<a href="#controls_android.tonemap.curve">android.<wbr/>tonemap.<wbr/>curve</a>*)  is less than max,<wbr/> the camera device will
-resample the curve to its internal representation,<wbr/> using linear
-interpolation.<wbr/></p>
+              <p>If the actual number of points provided by the application (in <a href="#controls_android.tonemap.curve">android.<wbr/>tonemap.<wbr/>curve</a>*) is
+less than this maximum,<wbr/> the camera device will resample the curve to its internal
+representation,<wbr/> using linear interpolation.<wbr/></p>
 <p>The output curves in the result metadata may have a different number
 of points than the input curves,<wbr/> and will represent the actual
 hardware curves used as closely as possible when linearly interpolated.<wbr/></p>
@@ -21521,13 +21814,15 @@ hardware curves used as closely as possible when linearly interpolated.<wbr/></p
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>The set of tonemapping modes supported by this camera device.<wbr/></p>
+              <p>List of tonemapping modes for <a href="#controls_android.tonemap.mode">android.<wbr/>tonemap.<wbr/>mode</a> that are supported by this camera
+device.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
+              <p>Any value listed in <a href="#controls_android.tonemap.mode">android.<wbr/>tonemap.<wbr/>mode</a></p>
             </td>
 
             <td class="entry_tags">
@@ -21539,9 +21834,8 @@ hardware curves used as closely as possible when linearly interpolated.<wbr/></p
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>This tag lists the valid modes for <a href="#controls_android.tonemap.mode">android.<wbr/>tonemap.<wbr/>mode</a>.<wbr/></p>
-<p>Full-capability camera devices must always support CONTRAST_<wbr/>CURVE and
-FAST.<wbr/></p>
+              <p>Camera devices that support the MANUAL_<wbr/>POST_<wbr/>PROCESSING capability will always list
+CONTRAST_<wbr/>CURVE and FAST.<wbr/> This includes all FULL level devices.<wbr/></p>
             </td>
           </tr>
 
@@ -21607,11 +21901,9 @@ CONTRAST_<wbr/>CURVE.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              same as android.<wbr/>tonemap.<wbr/>curve<wbr/>Red
             </td>
 
             <td class="entry_range">
-              <p>same as <a href="#controls_android.tonemap.curveRed">android.<wbr/>tonemap.<wbr/>curve<wbr/>Red</a></p>
             </td>
 
             <td class="entry_tags">
@@ -21662,11 +21954,9 @@ CONTRAST_<wbr/>CURVE.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              same as android.<wbr/>tonemap.<wbr/>curve<wbr/>Red
             </td>
 
             <td class="entry_range">
-              <p>same as <a href="#controls_android.tonemap.curveRed">android.<wbr/>tonemap.<wbr/>curve<wbr/>Red</a></p>
             </td>
 
             <td class="entry_tags">
@@ -21737,8 +22027,8 @@ as a floating-point value such that 0 == black and 1 == white.<wbr/></p>
 <pre><code><a href="#controls_android.tonemap.curveRed">android.<wbr/>tonemap.<wbr/>curve<wbr/>Red</a> =
   [ P0in,<wbr/> P0out,<wbr/> P1in,<wbr/> P1out,<wbr/> P2in,<wbr/> P2out,<wbr/> P3in,<wbr/> P3out,<wbr/> ...,<wbr/> PNin,<wbr/> PNout ]
 2 &lt;= N &lt;= <a href="#static_android.tonemap.maxCurvePoints">android.<wbr/>tonemap.<wbr/>max<wbr/>Curve<wbr/>Points</a></code></pre>
-<p>These are sorted in order of increasing <code>Pin</code>; it is always
-guaranteed that input values 0.<wbr/>0 and 1.<wbr/>0 are included in the list to
+<p>These are sorted in order of increasing <code>Pin</code>; it is
+required that input values 0.<wbr/>0 and 1.<wbr/>0 are included in the list to
 define a complete mapping.<wbr/> For input values between control points,<wbr/>
 the camera device must linearly interpolate between the control
 points.<wbr/></p>
@@ -21939,6 +22229,7 @@ the cost of reduced frame rate compared to raw sensor output.<wbr/></p></span>
             </td>
 
             <td class="entry_range">
+              <p><a href="#static_android.tonemap.availableToneMapModes">android.<wbr/>tonemap.<wbr/>available<wbr/>Tone<wbr/>Map<wbr/>Modes</a></p>
             </td>
 
             <td class="entry_tags">
@@ -21961,8 +22252,6 @@ are specified by normalized floating-point numbers.<wbr/></p>
 tables,<wbr/> selective chroma enhancement,<wbr/> or other non-linear color
 transforms will be disabled when <a href="#controls_android.tonemap.mode">android.<wbr/>tonemap.<wbr/>mode</a> is
 CONTRAST_<wbr/>CURVE.<wbr/></p>
-<p>This must be set to a valid mode in
-<a href="#static_android.tonemap.availableToneMapModes">android.<wbr/>tonemap.<wbr/>available<wbr/>Tone<wbr/>Map<wbr/>Modes</a>.<wbr/></p>
 <p>When using either FAST or HIGH_<wbr/>QUALITY,<wbr/> the camera device will
 emit its own tonemap curve in <a href="#controls_android.tonemap.curve">android.<wbr/>tonemap.<wbr/>curve</a>.<wbr/>
 These values are always available,<wbr/> and as close as possible to the
@@ -22291,7 +22580,6 @@ doesn't violate the above rules.<wbr/></p>
             </td>
 
             <td class="entry_range">
-              <p>Default value is LIMITED.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -22304,7 +22592,7 @@ doesn't violate the above rules.<wbr/></p>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
               <p>Camera devices will come in three flavors: LEGACY,<wbr/> LIMITED and FULL.<wbr/></p>
-<p>A FULL device has the most support possible and will support below capabilities:</p>
+<p>A FULL device will support below capabilities:</p>
 <ul>
 <li>30fps at maximum resolution (== sensor resolution) is preferred,<wbr/> more than 20fps is required.<wbr/></li>
 <li>Per frame control (<a href="#static_android.sync.maxLatency">android.<wbr/>sync.<wbr/>max<wbr/>Latency</a> <code>==</code> PER_<wbr/>FRAME_<wbr/>CONTROL)</li>
@@ -22318,6 +22606,16 @@ doesn't violate the above rules.<wbr/></p>
 </ul>
 <p>A LIMITED device may have some or none of the above characteristics.<wbr/>
 To find out more refer to <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a>.<wbr/></p>
+<p>Some features are not part of any particular hardware level or capability and must be
+queried separately.<wbr/> These include:</p>
+<ul>
+<li>Calibrated timestamps (<a href="#static_android.sensor.info.timestampSource">android.<wbr/>sensor.<wbr/>info.<wbr/>timestamp<wbr/>Source</a> <code>==</code> REALTIME)</li>
+<li>Precision lens control (<a href="#static_android.lens.info.focusDistanceCalibration">android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration</a> <code>==</code> CALIBRATED)</li>
+<li>Face detection (<a href="#static_android.statistics.info.availableFaceDetectModes">android.<wbr/>statistics.<wbr/>info.<wbr/>available<wbr/>Face<wbr/>Detect<wbr/>Modes</a>)</li>
+<li>Optical or electrical image stabilization
+  (<a href="#static_android.lens.info.availableOpticalStabilization">android.<wbr/>lens.<wbr/>info.<wbr/>available<wbr/>Optical<wbr/>Stabilization</a>,<wbr/>
+   <a href="#static_android.control.availableVideoStabilizationModes">android.<wbr/>control.<wbr/>available<wbr/>Video<wbr/>Stabilization<wbr/>Modes</a>)</li>
+</ul>
 <p>A LEGACY device does not support per-frame control,<wbr/> manual sensor control,<wbr/> manual
 post-processing,<wbr/> arbitrary cropping regions,<wbr/> and has relaxed performance constraints.<wbr/></p>
 <p>Each higher level supports everything the lower level supports
@@ -22429,9 +22727,9 @@ to its current values,<wbr/> or is free to vary.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>When set to ON,<wbr/> the values used for black-level
+              <p>When set to <code>true</code> (ON),<wbr/> the values used for black-level
 compensation will not change until the lock is set to
-OFF.<wbr/></p>
+<code>false</code> (OFF).<wbr/></p>
 <p>Since changes to certain capture parameters (such as
 exposure time) may require resetting of black level
 compensation,<wbr/> the camera device must report whether setting
@@ -22834,11 +23132,11 @@ result's state becomes synchronized (by setting
             </td>
 
             <td class="entry_units">
-              number of processed requests
+              Frame counts
             </td>
 
             <td class="entry_range">
-              <p>&gt;= -1</p>
+              <p>A positive value,<wbr/> PER_<wbr/>FRAME_<wbr/>CONTROL,<wbr/> or UNKNOWN.<wbr/></p>
             </td>
 
             <td class="entry_tags">
diff --git a/camera/docs/metadata_helpers.py b/camera/docs/metadata_helpers.py
index f0828ace..83e46c95 100644
--- a/camera/docs/metadata_helpers.py
+++ b/camera/docs/metadata_helpers.py
@@ -659,6 +659,46 @@ def jenum_value(enum_entry, enum_value):
   cname = csym(enum_entry.name)
   return cname[cname.find('_') + 1:] + '_' + enum_value.name
 
+def generate_extra_javadoc_detail(entry):
+  """
+  Returns a function to add extra details for an entry into a string for inclusion into
+  javadoc. Adds information about units, the list of enum values for this key, and the valid
+  range.
+  """
+  def inner(text):
+    if entry.units:
+      text += '\n\n<b>Units</b>: %s\n' % (dedent(entry.units))
+    if entry.enum and not (entry.typedef and entry.typedef.languages.get('java')):
+      text += '\n\n<b>Possible values:</b>\n<ul>\n'
+      for value in entry.enum.values:
+        if not value.hidden:
+          text += '  <li>{@link #%s %s}</li>\n' % ( jenum_value(entry, value ), value.name )
+      text += '</ul>\n'
+    if entry.range:
+      if entry.enum and not (entry.typedef and entry.typedef.languages.get('java')):
+        text += '\n\n<b>Available values for this device:</b><br>\n'
+      else:
+        text += '\n\n<b>Range of valid values:</b><br>\n'
+      text += '%s\n' % (dedent(entry.range))
+    if entry.hwlevel != 'legacy': # covers any of (None, 'limited', 'full')
+      text += '\n\n<b>Optional</b> - This value may be {@code null} on some devices.\n'
+    if entry.hwlevel == 'full':
+      text += \
+        '\n<b>Full capability</b> - \n' + \
+        'Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the\n' + \
+        'android.info.supportedHardwareLevel key\n'
+    if entry.hwlevel == 'limited':
+      text += \
+        '\n<b>Limited capability</b> - \n' + \
+        'Present on all camera devices that report being at least {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED HARDWARE_LEVEL_LIMITED} devices in the\n' + \
+        'android.info.supportedHardwareLevel key\n'
+    if entry.hwlevel == 'legacy':
+      text += "\nThis key is available on all devices."
+
+    return text
+  return inner
+
+
 def javadoc(metadata, indent = 4):
   """
   Returns a function to format a markdown syntax text block as a
@@ -733,7 +773,7 @@ def javadoc(metadata, indent = 4):
       # Indent each line
       # Add ' * ' to it for stylistic reasons
       # Strip right side of trailing whitespace
-      return (comment_prefix + line.lstrip()).rstrip()
+      return (comment_prefix + line).rstrip()
 
     # Process each line with above filter
     javatext = "\n".join(line_filter(i) for i in javatext.split("\n")) + "\n"
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index fe96508a..c3a8eb4e 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -228,6 +228,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>A color transform matrix to use to transform
           from sensor RGB color space to output linear sRGB color space.
           </description>
+          <units>Unitless scale factors</units>
           <details>This matrix is either set by the camera device when the request
           android.colorCorrection.mode is not TRANSFORM_MATRIX, or
           directly by the application in the request when the
@@ -248,6 +249,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           </array>
           <description>Gains applying to Bayer raw color channels for
           white-balance.</description>
+          <units>Unitless gain factors</units>
           <details>
           These per-channel gains are either set by the camera device
           when the request android.colorCorrection.mode is not
@@ -292,10 +294,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>
             Mode of operation for the chromatic aberration correction algorithm.
           </description>
+          <range>android.colorCorrection.availableAberrationModes</range>
           <details>
-            This must be set to a valid mode from
-            android.colorCorrection.availableAberrationModes.
-
             Chromatic (color) aberration is caused by the fact that different wavelengths of light
             can not focus on the same point after exiting from the lens. This metadata defines
             the high level control of chromatic aberration correction algorithm, which aims to
@@ -329,19 +329,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>
-            The set of aberration correction modes supported by this camera device.
+            List of aberration correction modes for android.colorCorrection.aberrationMode that are
+            supported by this camera device.
           </description>
-          <range>
-            The subset of aberration correction mode from those specified in
-            android.colorCorrection.aberrationMode.
-          </range>
+          <range>Any value listed in android.colorCorrection.aberrationMode</range>
           <details>
-            This metadata lists the valid modes for android.colorCorrection.aberrationMode.
-            If no aberration correction modes are available for a device, this list will solely include
+            This key lists the valid modes for android.colorCorrection.aberrationMode.  If no
+            aberration correction modes are available for a device, this list will solely include
             OFF mode.
 
-            For FULL capability device (android.info.supportedHardwareLevel `==` FULL), OFF must be
-            included.
+            For FULL capability device (android.info.supportedHardwareLevel `==` FULL), OFF is
+            always included.
 
             LEGACY devices will always only support FAST mode.
           </details>
@@ -411,7 +409,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             android.control.aeAvailableAntibandingModes key contains
             the available modes for a given camera device.
 
-            The default mode is AUTO, which must be supported by all
+            The default mode is AUTO, which is supported by all
             camera devices.
 
             If manual exposure control is enabled (by setting
@@ -436,7 +434,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         <entry name="aeExposureCompensation" type="int32" visibility="public" hwlevel="legacy">
           <description>Adjustment to auto-exposure (AE) target image
           brightness.</description>
-          <units>count of positive/negative EV steps</units>
+          <units>Compensation steps</units>
           <range>android.control.aeCompensationRange</range>
           <details>
           The adjustment is measured as a count of steps, with the
@@ -479,9 +477,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           </enum>
           <description>Whether auto-exposure (AE) is currently locked to its latest
           calculated values.</description>
-          <details>Note that even when AE is locked, the flash may be
-          fired if the android.control.aeMode is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
-          ON_AUTO_FLASH_REDEYE.
+          <details>
+          When set to `true` (ON), the AE algorithm is locked to its latest parameters,
+          and will not change exposure settings until the lock is set to `false` (OFF).
+
+          Note that even when AE is locked, the flash may be fired if
+          the android.control.aeMode is ON_AUTO_FLASH /
+          ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE.
 
           When android.control.aeExposureCompensation is changed, even if the AE lock
           is ON, the camera device will still adjust its exposure value.
@@ -493,6 +495,19 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the
           android.control.aeMode is ON_ALWAYS_FLASH, the scene may become overexposed.
 
+          Since the camera device has a pipeline of in-flight requests, the settings that
+          get locked do not necessarily correspond to the settings that were present in the
+          latest capture result received from the camera device, since additional captures
+          and AE updates may have occurred even before the result was sent out. If an
+          application is switching between automatic and manual control and wishes to eliminate
+          any flicker during the switch, the following procedure is recommended:
+
+            1. Starting in auto-AE mode:
+            2. Lock AE
+            3. Wait for the first result to be output that has the AE locked
+            4. Copy exposure settings from that result into a request, set the request to manual AE
+            5. Submit the capture request, proceed to run manual AE as desired.
+
           See android.control.aeState for AE lock related state transition details.
           </details>
           <tag id="BC" />
@@ -598,30 +613,41 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>5</size>
             <size>area_count</size>
           </array>
-          <description>List of areas to use for
-          metering.</description>
-          <range>`area_count &lt;= android.control.maxRegionsAe`</range>
+          <description>List of metering areas to use for auto-exposure adjustment.</description>
+          <units>Pixel coordinates within android.sensor.info.activeArraySize</units>
+          <range>Coordinates must be between `[(0,0), (width, height))` of
+          android.sensor.info.activeArraySize</range>
           <details>
-              Optional. Not available if android.control.maxRegionsAe is 0.
+              Not available if android.control.maxRegionsAe is 0.
               Otherwise will always be present.
 
+              The maximum number of regions supported by the device is determined by the value
+              of android.control.maxRegionsAe.
+
               The coordinate system is based on the active pixel array,
               with (0,0) being the top-left pixel in the active pixel array, and
               (android.sensor.info.activeArraySize.width - 1,
               android.sensor.info.activeArraySize.height - 1) being the
               bottom-right pixel in the active pixel array.
 
-              The weight must range from 0 to 1000, and represents a weight
+              The weight must be within `[0, 1000]`, and represents a weight
               for every pixel in the area. This means that a large metering area
               with the same weight as a smaller area will have more effect in
               the metering result. Metering areas can partially overlap and the
               camera device will add the weights in the overlap region.
 
-              If all regions have 0 weight, then no specific metering area
-              needs to be used by the camera device. If the metering region is
-              outside the used android.scaler.cropRegion returned in capture result metadata,
-              the camera device will ignore the sections outside the region and output the
-              used sections in the result metadata.
+              The weights are relative to weights of other exposure metering regions, so if only one
+              region is used, all non-zero weights will have the same effect. A region with 0
+              weight is ignored.
+
+              If all regions have 0 weight, then no specific metering area needs to be used by the
+              camera device.
+
+              If the metering region is outside the used android.scaler.cropRegion returned in
+              capture result metadata, the camera device will ignore the sections outside the crop
+              region and output only the intersection rectangle as the metering region in the result
+              metadata.  If the region is entirely outside the crop region, it will be ignored and
+              not reported in the result metadata.
           </details>
           <hal_details>
               The HAL level representation of MeteringRectangle[] is a
@@ -638,11 +664,14 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <array>
             <size>2</size>
           </array>
-          <description>Range over which fps can be adjusted to
-          maintain exposure.</description>
-          <range>android.control.aeAvailableTargetFpsRanges</range>
+          <description>Range over which the auto-exposure routine can
+          adjust the capture frame rate to maintain good
+          exposure.</description>
+          <units>Frames per second (FPS)</units>
+          <range>Any of the entries in android.control.aeAvailableTargetFpsRanges</range>
           <details>Only constrains auto-exposure (AE) algorithm, not
-          manual control of android.sensor.exposureTime</details>
+          manual control of android.sensor.exposureTime and
+          android.sensor.frameDuration.</details>
           <tag id="BC" />
         </entry>
         <entry name="aePrecaptureTrigger" type="byte" visibility="public"
@@ -679,7 +708,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           The exact effect of auto-exposure (AE) precapture trigger
           depends on the current AE mode and state; see
           android.control.aeState for AE precapture state transition
-          details.</details>
+          details.
+
+          On LEGACY-level devices, the precapture trigger is not supported;
+          capturing a high-resolution JPEG image will automatically trigger a
+          precapture sequence before the high-resolution capture, including
+          potentially firing a pre-capture flash.
+          </details>
           <tag id="BC" />
         </entry>
         <entry name="afMode" type="byte" visibility="public" enum="true"
@@ -810,30 +845,41 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>5</size>
             <size>area_count</size>
           </array>
-          <description>List of areas to use for focus
-          estimation.</description>
-          <range>`area_count &lt;= android.control.maxRegions[2]`</range>
+          <description>List of metering areas to use for auto-focus.</description>
+          <units>Pixel coordinates within android.sensor.info.activeArraySize</units>
+          <range>Coordinates must be between `[(0,0), (width, height))` of
+          android.sensor.info.activeArraySize</range>
           <details>
-              Optional. Not available if android.control.maxRegionsAf is 0.
+              Not available if android.control.maxRegionsAf is 0.
               Otherwise will always be present.
 
+              The maximum number of focus areas supported by the device is determined by the value
+              of android.control.maxRegionsAf.
+
               The coordinate system is based on the active pixel array,
               with (0,0) being the top-left pixel in the active pixel array, and
               (android.sensor.info.activeArraySize.width - 1,
               android.sensor.info.activeArraySize.height - 1) being the
               bottom-right pixel in the active pixel array.
 
-              The weight must range from 0 to 1000, and represents a weight
+              The weight must be within `[0, 1000]`, and represents a weight
               for every pixel in the area. This means that a large metering area
               with the same weight as a smaller area will have more effect in
               the metering result. Metering areas can partially overlap and the
               camera device will add the weights in the overlap region.
 
-              If all regions have 0 weight, then no specific metering area
-              needs to be used by the camera device. If the metering region is
-              outside the used android.scaler.cropRegion returned in capture result metadata,
-              the camera device will ignore the sections outside the region and output the
-              used sections in the result metadata.
+              The weights are relative to weights of other metering regions, so if only one region
+              is used, all non-zero weights will have the same effect. A region with 0 weight is
+              ignored.
+
+              If all regions have 0 weight, then no specific metering area needs to be used by the
+              camera device.
+
+              If the metering region is outside the used android.scaler.cropRegion returned in
+              capture result metadata, the camera device will ignore the sections outside the crop
+              region and output only the intersection rectangle as the metering region in the result
+              metadata. If the region is entirely outside the crop region, it will be ignored and
+              not reported in the result metadata.
           </details>
           <hal_details>
               The HAL level representation of MeteringRectangle[] is a
@@ -894,7 +940,24 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           </enum>
           <description>Whether auto-white balance (AWB) is currently locked to its
           latest calculated values.</description>
-          <details>Note that AWB lock is only meaningful when
+          <details>
+          When set to `true` (ON), the AWB algorithm is locked to its latest parameters,
+          and will not change color balance settings until the lock is set to `false` (OFF).
+
+          Since the camera device has a pipeline of in-flight requests, the settings that
+          get locked do not necessarily correspond to the settings that were present in the
+          latest capture result received from the camera device, since additional captures
+          and AWB updates may have occurred even before the result was sent out. If an
+          application is switching between automatic and manual control and wishes to eliminate
+          any flicker during the switch, the following procedure is recommended:
+
+            1. Starting in auto-AWB mode:
+            2. Lock AWB
+            3. Wait for the first result to be output that has the AWB locked
+            4. Copy AWB settings from that result into a request, set the request to manual AWB
+            5. Submit the capture request, proceed to run manual AWB as desired.
+
+          Note that AWB lock is only meaningful when
           android.control.awbMode is in the AUTO mode; in other modes,
           AWB is already fixed to a specific setting.
 
@@ -1067,13 +1130,18 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>5</size>
             <size>area_count</size>
           </array>
-          <description>List of areas to use for illuminant
+          <description>List of metering areas to use for auto-white-balance illuminant
           estimation.</description>
-          <range>`area_count &lt;= android.control.maxRegions[1]`</range>
+          <units>Pixel coordinates within android.sensor.info.activeArraySize</units>
+          <range>Coordinates must be between `[(0,0), (width, height))` of
+          android.sensor.info.activeArraySize</range>
           <details>
-              Optional. Not available if android.control.maxRegionsAwb is 0.
+              Not available if android.control.maxRegionsAwb is 0.
               Otherwise will always be present.
 
+              The maximum number of regions supported by the device is determined by the value
+              of android.control.maxRegionsAwb.
+
               The coordinate system is based on the active pixel array,
               with (0,0) being the top-left pixel in the active pixel array, and
               (android.sensor.info.activeArraySize.width - 1,
@@ -1086,11 +1154,18 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               the metering result. Metering areas can partially overlap and the
               camera device will add the weights in the overlap region.
 
-              If all regions have 0 weight, then no specific metering area
-              needs to be used by the camera device. If the metering region is
-              outside the used android.scaler.cropRegion returned in capture result metadata,
-              the camera device will ignore the sections outside the region and output the
-              used sections in the result metadata.
+              The weights are relative to weights of other white balance metering regions, so if
+              only one region is used, all non-zero weights will have the same effect. A region with
+              0 weight is ignored.
+
+              If all regions have 0 weight, then no specific metering area needs to be used by the
+              camera device.
+
+              If the metering region is outside the used android.scaler.cropRegion returned in
+              capture result metadata, the camera device will ignore the sections outside the crop
+              region and output only the intersection rectangle as the metering region in the result
+              metadata.  If the region is entirely outside the crop region, it will be ignored and
+              not reported in the result metadata.
           </details>
           <hal_details>
               The HAL level representation of MeteringRectangle[] is a
@@ -1149,13 +1224,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           auto-focus, auto-white balance) routines about the purpose
           of this capture, to help the camera device to decide optimal 3A
           strategy.</description>
-          <range>All must be supported except for ZERO_SHUTTER_LAG and MANUAL.</range>
           <details>This control (except for MANUAL) is only effective if
           `android.control.mode != OFF` and any 3A routine is active.
 
           ZERO_SHUTTER_LAG will be supported if android.request.availableCapabilities
           contains ZSL. MANUAL will be supported if android.request.availableCapabilities
-          contains MANUAL_SENSOR.</details>
+          contains MANUAL_SENSOR. Other intent values are always supported.
+          </details>
           <tag id="BC" />
         </entry>
         <entry name="effectMode" type="byte" visibility="public" enum="true"
@@ -1227,9 +1302,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           implementor of the camera device, and should not be
           depended on to be consistent (or present) across all
           devices.
-
-          A color effect will only be applied if
-          android.control.mode != OFF.
           </details>
           <tag id="BC" />
         </entry>
@@ -1280,10 +1352,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             discarded by the camera device.
             </notes></value>
           </enum>
-          <description>Overall mode of 3A control
+          <description>Overall mode of 3A (auto-exposure, auto-white-balance, auto-focus) control
           routines.</description>
-          <range>all must be supported</range>
-          <details>High-level 3A control. When set to OFF, all 3A control
+          <details>
+          This is a top-level 3A control switch. When set to OFF, all 3A control
           by the camera device is disabled. The application must set the fields for
           capture parameters itself.
 
@@ -1304,7 +1376,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
 
           LEGACY mode devices will only support AUTO and USE_SCENE_MODE modes.
           LIMITED mode devices will only support OFF and OFF_KEEP_STATE if they
-          support the MANUAL_SENSOR capability.
+          support the MANUAL_SENSOR and MANUAL_POST_PROCSESING capabilities.
+          FULL mode devices will always support OFF and OFF_KEEP_STATE.
           </details>
           <tag id="BC" />
         </entry>
@@ -1492,17 +1565,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             </value>
           </enum>
           <description>
-          A camera mode optimized for conditions typical in a particular
-          capture setting.
+          Control for which scene mode is currently active.
           </description>
           <range>android.control.availableSceneModes</range>
           <details>
+          Scene modes are custom camera modes optimized for a certain set of conditions and
+          capture settings.
+
           This is the mode that that is active when
           `android.control.mode == USE_SCENE_MODE`. Aside from FACE_PRIORITY,
           these modes will disable android.control.aeMode,
           android.control.awbMode, and android.control.afMode while in use.
-          The scene modes available for a given camera device are listed in
-          android.control.availableSceneModes.
 
           The interpretation and implementation of these scene modes is left
           to the implementor of the camera device. Their behavior will not be
@@ -1539,24 +1612,23 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>Whether video stabilization is
           active.</description>
           <details>
-          Video stabilization automatically translates and scales images from the camera
-          in order to stabilize motion between consecutive frames.
+          Video stabilization automatically translates and scales images from
+          the camera in order to stabilize motion between consecutive frames.
 
           If enabled, video stabilization can modify the
           android.scaler.cropRegion to keep the video stream stabilized.
 
-          Switching between different video stabilization modes may take several frames
-          to initialize, the camera device will report the current mode in capture result
-          metadata. For example, When "ON" mode is requested, the video stabilization modes
-          in the first several capture results may still be "OFF", and it will become "ON"
-          when the initialization is done.
-
-          If a camera device supports both this mode and OIS (android.lens.opticalStabilizationMode),
-          turning both modes on may produce undesirable interaction, so it is recommended not to
-          enable both at the same time.
-
-          Some LEGACY camera devices will not support changing video stabilization
-          mode; in this case the value will always override to OFF.
+          Switching between different video stabilization modes may take several
+          frames to initialize, the camera device will report the current mode
+          in capture result metadata. For example, When "ON" mode is requested,
+          the video stabilization modes in the first several capture results may
+          still be "OFF", and it will become "ON" when the initialization is
+          done.
+
+          If a camera device supports both this mode and OIS
+          (android.lens.opticalStabilizationMode), turning both modes on may
+          produce undesirable interaction, so it is recommended not to enable
+          both at the same time.
           </details>
           <tag id="BC" />
         </entry>
@@ -1569,14 +1641,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>
-            The set of auto-exposure antibanding modes that are
+            List of auto-exposure antibanding modes for android.control.aeAntibandingMode that are
             supported by this camera device.
           </description>
+          <range>Any value listed in android.control.aeAntibandingMode</range>
           <details>
             Not all of the auto-exposure anti-banding modes may be
             supported by a given camera device. This field lists the
             valid anti-banding modes that the application may request
-            for this camera device; they must include AUTO.
+            for this camera device with the
+            android.control.aeAntibandingMode control. This list
+            always includes AUTO.
           </details>
           <tag id="BC" />
         </entry>
@@ -1587,9 +1662,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>
-            The set of auto-exposure modes that are supported by this
-            camera device.
+            List of auto-exposure modes for android.control.aeMode that are supported by this camera
+            device.
           </description>
+          <range>Any value listed in android.control.aeMode</range>
           <details>
             Not all the auto-exposure modes may be supported by a
             given camera device, especially if no flash unit is
@@ -1617,8 +1693,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>2</size>
             <size>n</size>
           </array>
-          <description>List of frame rate ranges supported by the
-          auto-exposure (AE) algorithm/hardware</description>
+          <description>List of frame rate ranges for android.control.aeTargetFpsRange supported by
+          this camera device.</description>
+          <units>Frames per second (FPS)</units>
+          <details>
+          For devices at the LIMITED level or above, this list will include at least (30, 30) for
+          constant-framerate recording.
+          </details>
           <tag id="BC" />
         </entry>
         <entry name="aeCompensationRange" type="int32" visibility="public"
@@ -1627,18 +1708,32 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <array>
             <size>2</size>
           </array>
-          <description>Maximum and minimum exposure compensation
-          setting, in counts of
-          android.control.aeCompensationStep.</description>
-          <range>At least (-2,2)/(exp compensation step
-          size)</range>
+          <description>Maximum and minimum exposure compensation values for
+          android.control.aeExposureCompensation, in counts of android.control.aeCompensationStep,
+          that are supported by this camera device.</description>
+          <range>
+            `Min.exposure compensation * android.control.aeCompensationStep &lt;= -2 EV`
+
+            `Max.exposure compensation * android.control.aeCompensationStep &gt;= 2 EV`
+          </range>
           <tag id="BC" />
         </entry>
         <entry name="aeCompensationStep" type="rational" visibility="public"
                hwlevel="legacy">
-          <description>Smallest step by which exposure compensation
-          can be changed</description>
-          <range>&lt;= 1/2</range>
+          <description>Smallest step by which the exposure compensation
+          can be changed.</description>
+          <units>Exposure Value (EV)</units>
+          <details>
+          This is the unit for android.control.aeExposureCompensation. For example, if this key has
+          a value of `1/2`, then a setting of `-2` for android.control.aeExposureCompensation means
+          that the target EV offset for the auto-exposure routine is -1 EV.
+
+          One unit of EV compensation changes the brightness of the captured image by a factor
+          of two. +1 EV doubles the image brightness, while -1 EV halves the image brightness.
+          </details>
+          <hal_details>
+            This must be less than or equal to 1/2.
+          </hal_details>
           <tag id="BC" />
         </entry>
         <entry name="afAvailableModes" type="byte" visibility="public"
@@ -1647,8 +1742,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <array>
             <size>n</size>
           </array>
-          <description>List of auto-focus (AF) modes that can be
-          selected with android.control.afMode.</description>
+          <description>
+          List of auto-focus (AF) modes for android.control.afMode that are
+          supported by this camera device.
+          </description>
+          <range>Any value listed in android.control.afMode</range>
           <details>
           Not all the auto-focus modes may be supported by a
           given camera device. This entry lists the valid modes for
@@ -1671,24 +1769,22 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>
-          List containing the subset of color effects
-          specified in android.control.effectMode that is supported by
-          this device.
+          List of color effects for android.control.effectMode that are supported by this camera
+          device.
           </description>
-          <range>
-          Any subset of enums from those specified in
-          android.control.effectMode.  OFF must be included in any subset.
-          </range>
+          <range>Any value listed in android.control.effectMode</range>
           <details>
           This list contains the color effect modes that can be applied to
-          images produced by the camera device. Only modes that have
-          been fully implemented for the current device may be included here.
+          images produced by the camera device.
           Implementations are not expected to be consistent across all devices.
-          If no color effect modes are available for a device, this should
-          simply be set to OFF.
+          If no color effect modes are available for a device, this will only list
+          OFF.
 
           A color effect will only be applied if
-          android.control.mode != OFF.
+          android.control.mode != OFF.  OFF is always included in this list.
+
+          This control has no effect on the operation of other control routines such
+          as auto-exposure, white balance, or focus.
           </details>
           <tag id="BC" />
         </entry>
@@ -1699,21 +1795,22 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>
-          List containing a subset of scene modes
-          specified in android.control.sceneMode.
+          List of scene modes for android.control.sceneMode that are supported by this camera
+          device.
           </description>
-          <range>
-          Any subset of the enums specified in android.control.sceneMode
-          not including DISABLED, or solely DISABLED if no
-          scene modes are available. FACE_PRIORITY must be included
-          if face detection is supported (i.e.`android.statistics.info.maxFaceCount &gt; 0`).
-          </range>
+          <range>Any value listed in android.control.sceneMode</range>
           <details>
           This list contains scene modes that can be set for the camera device.
           Only scene modes that have been fully implemented for the
           camera device may be included here. Implementations are not expected
-          to be consistent across all devices. If no scene modes are supported
-          by the camera device, this will be set to `[DISABLED]`.
+          to be consistent across all devices.
+
+          If no scene modes are supported by the camera device, this
+          will be set to DISABLED. Otherwise DISABLED will not be listed.
+
+          FACE_PRIORITY is always listed if face detection is
+          supported (i.e.`android.statistics.info.maxFaceCount &gt;
+          0`).
           </details>
           <tag id="BC" />
         </entry>
@@ -1723,9 +1820,14 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <array>
             <size>n</size>
           </array>
-          <description>List of video stabilization modes that can
-          be supported</description>
-          <range>OFF must be included</range>
+          <description>
+          List of video stabilization modes for android.control.videoStabilizationMode
+          that are supported by this camera device.
+          </description>
+          <range>Any value listed in android.control.videoStabilizationMode</range>
+          <details>
+          OFF will always be listed.
+          </details>
           <tag id="BC" />
         </entry>
         <entry name="awbAvailableModes" type="byte" visibility="public"
@@ -1734,8 +1836,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <array>
             <size>n</size>
           </array>
-          <description>The set of auto-white-balance modes (android.control.awbMode)
-          that are supported by this camera device.</description>
+          <description>
+          List of auto-white-balance modes for android.control.awbMode that are supported by this
+          camera device.
+          </description>
+          <range>Any value listed in android.control.awbMode</range>
           <details>
           Not all the auto-white-balance modes may be supported by a
           given camera device. This entry lists the valid modes for
@@ -1743,10 +1848,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
 
           All camera devices will support ON mode.
 
-          FULL mode camera devices will always support OFF mode,
-          which enables application control of white balance, by using
+          Camera devices that support the MANUAL_POST_PROCESSING capability will always support OFF
+          mode, which enables application control of white balance, by using
           android.colorCorrection.transform and android.colorCorrection.gains
-          (android.colorCorrection.mode must be set to TRANSFORM_MATRIX).
+          (android.colorCorrection.mode must be set to TRANSFORM_MATRIX). This includes all FULL
+          mode camera devices.
           </details>
           <tag id="BC" />
         </entry>
@@ -1771,15 +1877,16 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         <entry name="maxRegionsAe" type="int32" visibility="public"
                synthetic="true" hwlevel="legacy">
           <description>
-          List of the maximum number of regions that can be used for metering in
-          auto-exposure (AE);
-          this corresponds to the the maximum number of elements in
-          android.control.aeRegions.
+          The maximum number of metering regions that can be used by the auto-exposure (AE)
+          routine.
           </description>
-          <range>
-          Value will be &amp;gt;= 0. For FULL-capability devices, this
+          <range>Value will be &amp;gt;= 0. For FULL-capability devices, this
           value will be &amp;gt;= 1.
           </range>
+          <details>
+          This corresponds to the the maximum allowed number of elements in
+          android.control.aeRegions.
+          </details>
           <hal_details>This entry is private to the framework. Fill in
           maxRegions to have this entry be automatically populated.
           </hal_details>
@@ -1787,14 +1894,15 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         <entry name="maxRegionsAwb" type="int32" visibility="public"
                synthetic="true" hwlevel="legacy">
           <description>
-          List of the maximum number of regions that can be used for metering in
-          auto-white balance (AWB);
-          this corresponds to the the maximum number of elements in
-          android.control.awbRegions.
+          The maximum number of metering regions that can be used by the auto-white balance (AWB)
+          routine.
           </description>
-          <range>
-          Value will be &amp;gt;= 0.
+          <range>Value will be &amp;gt;= 0.
           </range>
+          <details>
+          This corresponds to the the maximum allowed number of elements in
+          android.control.awbRegions.
+          </details>
           <hal_details>This entry is private to the framework. Fill in
           maxRegions to have this entry be automatically populated.
           </hal_details>
@@ -1802,15 +1910,15 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         <entry name="maxRegionsAf" type="int32" visibility="public"
                synthetic="true" hwlevel="legacy">
           <description>
-          List of the maximum number of regions that can be used for metering in
-          auto-focus (AF);
-          this corresponds to the the maximum number of elements in
-          android.control.afRegions.
+          The maximum number of metering regions that can be used by the auto-focus (AF) routine.
           </description>
-          <range>
-          Value will be &amp;gt;= 0. For FULL-capability devices, this
+          <range>Value will be &amp;gt;= 0. For FULL-capability devices, this
           value will be &amp;gt;= 1.
           </range>
+          <details>
+          This corresponds to the the maximum allowed number of elements in
+          android.control.afRegions.
+          </details>
           <hal_details>This entry is private to the framework. Fill in
           maxRegions to have this entry be automatically populated.
           </hal_details>
@@ -2333,10 +2441,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           </enum>
           <description>Operation mode for edge
           enhancement.</description>
-          <details>Edge/sharpness/detail enhancement. OFF means no
-          enhancement will be applied by the camera device.
-
-          This must be set to one of the modes listed in android.edge.availableEdgeModes.
+          <range>android.edge.availableEdgeModes</range>
+          <details>Edge enhancement improves sharpness and details in the captured image. OFF means
+          no enhancement will be applied by the camera device.
 
           FAST/HIGH_QUALITY both mean camera device determined enhancement
           will be applied. HIGH_QUALITY mode indicates that the
@@ -2360,12 +2467,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>
-          The set of edge enhancement modes supported by this camera device.
+          List of edge enhancement modes for android.edge.mode that are supported by this camera
+          device.
           </description>
+          <range>Any value listed in android.edge.mode</range>
           <details>
-          This tag lists the valid modes for android.edge.mode.
-
-          Full-capability camera devices must always support OFF and FAST.
+          Full-capability camera devices must always support OFF; all devices will list FAST.
           </details>
           <tag id="V1" />
         </entry>
@@ -2448,9 +2555,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               <value>TRUE</value>
             </enum>
             <description>Whether this camera device has a
-            flash.</description>
-            <details>If no flash, none of the flash controls do
-            anything. All other metadata should return 0.</details>
+            flash unit.</description>
+            <details>
+            Will be `false` if no flash is available.
+
+            If there is no flash unit, none of the flash controls do
+            anything.</details>
             <tag id="BC" />
           </entry>
           <entry name="chargeDuration" type="int64">
@@ -2555,15 +2665,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             </value>
           </enum>
           <description>
-          Set operational mode for hot pixel correction.
+          Operational mode for hot pixel correction.
           </description>
+          <range>android.hotPixel.availableHotPixelModes</range>
           <details>
-          Valid modes for this camera device are listed in
-          android.hotPixel.availableHotPixelModes.
-
           Hotpixel correction interpolates out, or otherwise removes, pixels
-          that do not accurately encode the incoming light (i.e. pixels that
-          are stuck at an arbitrary value).
+          that do not accurately measure the incoming light (i.e. pixels that
+          are stuck at an arbitrary value or are oversensitive).
           </details>
           <tag id="V1" />
           <tag id="RAW" />
@@ -2576,12 +2684,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>
-          The set of hot pixel correction modes that are supported by this
+          List of hot pixel correction modes for android.hotPixel.mode that are supported by this
           camera device.
           </description>
+          <range>Any value listed in android.hotPixel.mode</range>
           <details>
-          This tag lists valid modes for android.hotPixel.mode.
-
           FULL mode camera devices will always support FAST.
           </details>
           <hal_details>
@@ -2606,6 +2713,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>
           A location object to use when generating image GPS metadata.
           </description>
+          <details>
+          Setting a location object in a request will include the GPS coordinates of the location
+          into any JPEG images captured based on the request. These coordinates can then be
+          viewed by anyone who receives the JPEG image.
+          </details>
         </entry>
         <entry name="gpsCoordinates" type="double" visibility="hidden"
         type_notes="latitude, longitude, altitude. First two in degrees, the third in meters"
@@ -2614,28 +2726,59 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>3</size>
           </array>
           <description>GPS coordinates to include in output JPEG
-          EXIF</description>
+          EXIF.</description>
           <range>(-180 - 180], [-90,90], [-inf, inf]</range>
           <tag id="BC" />
         </entry>
         <entry name="gpsProcessingMethod" type="byte" visibility="hidden"
                typedef="string" hwlevel="legacy">
           <description>32 characters describing GPS algorithm to
-          include in EXIF</description>
+          include in EXIF.</description>
           <units>UTF-8 null-terminated string</units>
           <tag id="BC" />
         </entry>
         <entry name="gpsTimestamp" type="int64" visibility="hidden" hwlevel="legacy">
           <description>Time GPS fix was made to include in
-          EXIF</description>
+          EXIF.</description>
           <units>UTC in seconds since January 1, 1970</units>
           <tag id="BC" />
         </entry>
         <entry name="orientation" type="int32" visibility="public" hwlevel="legacy">
-          <description>Orientation of JPEG image to
-          write</description>
+          <description>The orientation for a JPEG image.</description>
           <units>Degrees in multiples of 90</units>
           <range>0, 90, 180, 270</range>
+          <details>
+          The clockwise rotation angle in degrees, relative to the orientation
+          to the camera, that the JPEG picture needs to be rotated by, to be viewed
+          upright.
+
+          Camera devices may either encode this value into the JPEG EXIF header, or
+          rotate the image data to match this orientation.
+
+          Note that this orientation is relative to the orientation of the camera sensor, given
+          by android.sensor.orientation.
+
+          To translate from the device orientation given by the Android sensor APIs, the following
+          sample code may be used:
+
+              private int getJpegOrientation(CameraCharacteristics c, int deviceOrientation) {
+                  if (deviceOrientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return 0;
+                  int sensorOrientation = c.get(CameraCharacteristics.SENSOR_ORIENTATION);
+
+                  // Round device orientation to a multiple of 90
+                  deviceOrientation = (deviceOrientation + 45) / 90 * 90;
+
+                  // Reverse device orientation for front-facing cameras
+                  boolean facingFront = c.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_FRONT;
+                  if (facingFront) deviceOrientation = -deviceOrientation;
+
+                  // Calculate desired JPEG orientation relative to camera orientation to make
+                  // the image upright relative to the device orientation
+                  int jpegOrientation = (sensorOrientation + deviceOrientation + 360) % 360;
+
+                  return jpegOrientation;
+              }
+          </details>
           <tag id="BC" />
         </entry>
         <entry name="quality" type="byte" visibility="public" hwlevel="legacy">
@@ -2657,12 +2800,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>2</size>
           </array>
           <description>Resolution of embedded JPEG thumbnail.</description>
-          <range>Size must be one of the size from android.jpeg.availableThumbnailSizes</range>
+          <range>android.jpeg.availableThumbnailSizes</range>
           <details>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
           but the captured JPEG will still be a valid image.
 
-          When a jpeg image capture is issued, the thumbnail size selected should have
-          the same aspect ratio as the jpeg image.
+          For best results, when issuing a request for a JPEG image, the thumbnail size selected
+          should have the same aspect ratio as the main JPEG output.
 
           If the thumbnail image aspect ratio differs from the JPEG primary image aspect
           ratio, the camera device creates the thumbnail by cropping it from the primary image.
@@ -2687,10 +2830,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>2</size>
             <size>n</size>
           </array>
-          <description>Supported resolutions for the JPEG thumbnail.</description>
-          <range>Will include at least one valid resolution, plus
-          (0,0) for no thumbnail generation, and each size will be distinct.</range>
-          <details>Below condiditions will be satisfied for this size list:
+          <description>List of JPEG thumbnail sizes for android.jpeg.thumbnailSize supported by this
+          camera device.</description>
+          <details>
+          This list will include at least one non-zero resolution, plus `(0,0)` for indicating no
+          thumbnail should be generated.
+
+          Below condiditions will be satisfied for this size list:
 
           * The sizes will be sorted by increasing pixel area (width x height).
           If several resolutions have the same area, they will be sorted by increasing width.
@@ -2701,7 +2847,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           * Each output JPEG size in android.scaler.availableStreamConfigurations will have at least
           one corresponding size that has the same aspect ratio in availableThumbnailSizes,
           and vice versa.
-          * All non (0, 0) sizes will have non-zero widths and heights.</details>
+          * All non-`(0, 0)` sizes will have non-zero widths and heights.</details>
           <tag id="BC" />
         </entry>
         <entry name="maxSize" type="int32" visibility="system">
@@ -2750,13 +2896,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
     <section name="lens">
       <controls>
         <entry name="aperture" type="float" visibility="public" hwlevel="full">
-          <description>The ratio of lens focal length to the effective
-          aperture diameter.</description>
-          <units>f-number (f/NNN)</units>
+          <description>The desired lens aperture size, as a ratio of lens focal length to the
+          effective aperture diameter.</description>
+          <units>The f-number (f/N)</units>
           <range>android.lens.info.availableApertures</range>
-          <details>This will only be supported on the camera devices that
-          have variable aperture lens. The aperture value can only be
-          one of the values listed in android.lens.info.availableApertures.
+          <details>Setting this value is only supported on the camera devices that have a variable
+          aperture lens.
 
           When this is supported and android.control.aeMode is OFF,
           this can be set along with android.sensor.exposureTime,
@@ -2776,14 +2921,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         </entry>
         <entry name="filterDensity" type="float" visibility="public" hwlevel="full">
           <description>
-          State of lens neutral density filter(s).
+          The desired setting for the lens neutral density filter(s).
           </description>
-          <units>Steps of Exposure Value (EV).</units>
+          <units>Exposure Value (EV)</units>
           <range>android.lens.info.availableFilterDensities</range>
           <details>
-          This will not be supported on most camera devices. On devices
-          where this is supported, this may only be set to one of the
-          values included in android.lens.info.availableFilterDensities.
+          This control will not be supported on most camera devices.
 
           Lens filters are typically used to lower the amount of light the
           sensor is exposed to (measured in steps of EV). As used here, an EV
@@ -2802,9 +2945,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         </entry>
         <entry name="focalLength" type="float" visibility="public" hwlevel="legacy">
           <description>
-          The current lens focal length; used for optical zoom.
+          The desired lens focal length; used for optical zoom.
           </description>
-          <units>focal length in mm</units>
+          <units>Millimeters</units>
           <range>android.lens.info.availableFocalLengths</range>
           <details>
           This setting controls the physical focal length of the camera
@@ -2817,17 +2960,22 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           While the focal length is still changing, android.lens.state will
           be set to MOVING.
 
-          This is expected not to be supported on most devices.
+          Optical zoom will not be supported on most devices.
           </details>
           <tag id="V1" />
         </entry>
         <entry name="focusDistance" type="float" visibility="public" hwlevel="full">
-          <description>Distance to plane of sharpest focus,
+          <description>Desired distance to plane of sharpest focus,
           measured from frontmost surface of the lens.</description>
-          <units>See android.lens.info.focusDistanceCalibration for details.</units>
+          <units>See android.lens.info.focusDistanceCalibration for details</units>
           <range>&amp;gt;= 0</range>
-          <details>`0.0f` means infinity focus. Used value will be clamped
-          to `[0.0f, android.lens.info.minimumFocusDistance]`.
+          <details>
+          This control can be used for setting manual focus, on devices that support
+          the MANUAL_SENSOR capability and have a variable-focus lens (see
+          android.lens.info.minimumFocusDistance).
+
+          A value of `0.0f` means infinity focus. The value set will be clamped to
+          `[0.0f, android.lens.info.minimumFocusDistance]`.
 
           Like android.lens.focalLength, this setting won't be applied
           instantaneously, and it may take several frames before the lens
@@ -2869,9 +3017,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           optical stabilization modes in the first several capture results may still
           be "OFF", and it will become "ON" when the initialization is done.
 
-          If a camera device supports both OIS and EIS (android.control.videoStabilizationMode),
-          turning both modes on may produce undesirable interaction, so it is recommended not
-          to enable both at the same time.
+          If a camera device supports both OIS and digital image stabilization
+          (android.control.videoStabilizationMode), turning both modes on may produce undesirable
+          interaction, so it is recommended not to enable both at the same time.
 
           Not all devices will support OIS; see
           android.lens.info.availableOpticalStabilization for
@@ -2887,13 +3035,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <array>
               <size>n</size>
             </array>
-            <description>List of supported aperture
-            values.</description>
-            <range>one entry required, &amp;gt; 0</range>
-            <details>If the camera device doesn't support variable apertures,
-            listed value will be the fixed aperture.
+            <description>List of aperture size values for android.lens.aperture that are
+            supported by this camera device.</description>
+            <units>The aperture f-number</units>
+            <details>If the camera device doesn't support a variable lens aperture,
+            this list will contain only one value, which is the fixed aperture size.
 
-            If the camera device supports variable apertures, the aperture value
+            If the camera device supports a variable aperture, the aperture values
             in this list will be sorted in ascending order.</details>
             <tag id="V1" />
           </entry>
@@ -2903,17 +3051,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               <size>n</size>
             </array>
             <description>
-            List of supported neutral density filter values for
-            android.lens.filterDensity.
+            List of neutral density filter values for
+            android.lens.filterDensity that are supported by this camera device.
             </description>
+            <units>Exposure value (EV)</units>
             <range>
-            At least one value is required. Values must be &amp;gt;= 0.
+            Values are &amp;gt;= 0
             </range>
             <details>
-            If changing android.lens.filterDensity is not supported,
-            availableFilterDensities must contain only 0. Otherwise, this
-            list contains only the exact filter density values available on
-            this camera device.
+            If a neutral density filter is not supported by this camera device,
+            this list will contain only 0. Otherwise, this list will include every
+            filter density supported by the camera device, in ascending order.
             </details>
             <tag id="V1" />
           </entry>
@@ -2924,18 +3072,18 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               <size>n</size>
             </array>
             <description>
-            The available focal lengths for this device for use with
-            android.lens.focalLength.
+            List of focal lengths for android.lens.focalLength that are supported by this camera
+            device.
             </description>
+            <units>Millimeters</units>
             <range>
-            Each value in this list must be &amp;gt; 0. This list must
-            contain at least one value.
+            Values are &amp;gt; 0
             </range>
             <details>
-            If optical zoom is not supported, this will only report
-            a single value corresponding to the static focal length of the
-            device. Otherwise, this will report every focal length supported
-            by the device.
+            If optical zoom is not supported, this list will only contain
+            a single value corresponding to the fixed focal length of the
+            device. Otherwise, this list will include every focal length supported
+            by the camera device, in ascending order.
             </details>
             <tag id="BC" />
             <tag id="V1" />
@@ -2947,22 +3095,22 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               <size>n</size>
             </array>
             <description>
-            List containing a subset of the optical image
-            stabilization (OIS) modes specified in
-            android.lens.opticalStabilizationMode.
+            List of optical image stabilization (OIS) modes for
+            android.lens.opticalStabilizationMode that are supported by this camera device.
             </description>
+            <range>Any value listed in android.lens.opticalStabilizationMode</range>
             <details>
-            If OIS is not implemented for a given camera device, this will
+            If OIS is not supported by a given camera device, this list will
             contain only OFF.
             </details>
             <tag id="V1" />
           </entry>
           <entry name="hyperfocalDistance" type="float" visibility="public" optional="true"
                  hwlevel="limited">
-            <description>Optional. Hyperfocal distance for this lens.</description>
-            <units>See android.lens.info.focusDistanceCalibration for details.</units>
-            <range>If lens is fixed focus, &amp;gt;= 0. If lens has focuser unit, the range is
-            `(0, android.lens.info.minimumFocusDistance]`</range>
+            <description>Hyperfocal distance for this lens.</description>
+            <units>See android.lens.info.focusDistanceCalibration for details</units>
+            <range>If lens is fixed focus, &amp;gt;= 0. If lens has focuser unit, the value is
+            within `(0.0f, android.lens.info.minimumFocusDistance]`</range>
             <details>
             If the lens is not fixed focus, the camera device will report this
             field when android.lens.info.focusDistanceCalibration is APPROXIMATE or CALIBRATED.
@@ -2971,10 +3119,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <entry name="minimumFocusDistance" type="float" visibility="public" optional="true"
                  hwlevel="limited">
             <description>Shortest distance from frontmost surface
-            of the lens that can be focused correctly.</description>
-            <units>See android.lens.info.focusDistanceCalibration for details.</units>
+            of the lens that can be brought into sharp focus.</description>
+            <units>See android.lens.info.focusDistanceCalibration for details</units>
             <range>&amp;gt;= 0</range>
-            <details>If the lens is fixed-focus, this should be
+            <details>If the lens is fixed-focus, this will be
             0.</details>
             <hal_details>Mandatory for FULL devices; LIMITED devices
             must always set this value to 0 for fixed-focus; and may omit
@@ -3044,6 +3192,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             focus related metadata entries, i.e. android.lens.focusDistance,
             android.lens.focusRange, android.lens.info.hyperfocalDistance, and
             android.lens.info.minimumFocusDistance.
+
+            APPROXIMATE and CALIBRATED devices report the focus metadata in
+            units of diopters (1/meter), so `0.0f` represents focusing at infinity,
+            and increasing positive numbers represent focusing closer and closer
+            to the camera device. The focus distance control also uses diopters
+            on these devices.
+
+            UNCALIBRATED devices do not use units that are directly comparable
+            to any real physical measurement, but `0.0f` still represents farthest
+            focus, and android.lens.info.minimumFocusDistance represents the
+            nearest focus the device can achieve.
             </details>
             <hal_details>
             For devices advertise APPROXIMATE quality or higher, diopters 0 (infinity
@@ -3127,8 +3286,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           </array>
           <description>The range of scene distances that are in
           sharp focus (depth of field).</description>
-          <units>pair of focus distances in diopters: (near,
-          far), see android.lens.info.focusDistanceCalibration for details.</units>
+          <units>A pair of focus distances in diopters: (near,
+          far); see android.lens.info.focusDistanceCalibration for details.</units>
           <range>&amp;gt;=0</range>
           <details>If variable focus not supported, can still report
           fixed depth of field range</details>
@@ -3197,18 +3356,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             relative to sensor output.</notes></value>
           </enum>
           <description>Mode of operation for the noise reduction algorithm.</description>
-          <details>Noise filtering control. OFF means no noise reduction
-          will be applied by the camera device.
-
-          This must be set to a valid mode from
-          android.noiseReduction.availableNoiseReductionModes.
+          <range>android.noiseReduction.availableNoiseReductionModes</range>
+          <details>The noise reduction algorithm attempts to improve image quality by removing
+          excessive noise added by the capture process, especially in dark conditions.
+          OFF means no noise reduction will be applied by the camera device.
 
           FAST/HIGH_QUALITY both mean camera device determined noise filtering
           will be applied. HIGH_QUALITY mode indicates that the camera device
           will use the highest-quality noise filtering algorithms,
           even if it slows down capture rate. FAST means the camera device will not
           slow down capture rate when applying noise filtering.
-        </details>
+          </details>
           <tag id="V1" />
         </entry>
         <entry name="strength" type="byte">
@@ -3226,12 +3384,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>
-          The set of noise reduction modes supported by this camera device.
+          List of noise reduction modes for android.noiseReduction.mode that are supported
+          by this camera device.
           </description>
+          <range>Any value listed in android.noiseReduction.mode</range>
           <details>
-          This tag lists the valid modes for android.noiseReduction.mode.
-
-          Full-capability camera devices must always support OFF and FAST.
+          Full-capability camera devices will always support OFF and FAST.
 
           Legacy-capability camera devices will only support FAST mode.
           </details>
@@ -3525,7 +3683,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           For full guarantees, query StreamConfigurationMap#getOutputStallDuration with
           a processed format -- it will return 0 for a non-stalling stream.
 
-          LEGACY devices will support up to 3 processing/non-stalling streams.
+          LEGACY devices will support at least 2 processing/non-stalling streams.
           </details>
         </entry>
         <entry name="maxNumOutputProcStalling" type="int32" visibility="public" synthetic="true" hwlevel="legacy">
@@ -3546,7 +3704,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           be any non-`RAW` and supported format provided by android.scaler.streamConfigurationMap.
 
           A processed and stalling format is defined as any non-RAW format with a stallDurations &amp;gt; 0.
-          Typically only the `JPEG` format (ImageFormat#JPEG)
+          Typically only the `JPEG` format (ImageFormat#JPEG) is a stalling format.
 
           For full guarantees, query StreamConfigurationMap#getOutputStallDuration with
           a processed format -- it will return a non-0 value for a stalling stream.
@@ -3784,7 +3942,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               </notes>
             </value>
           </enum>
-          <description>List of capabilities that the camera device
+          <description>List of capabilities that this camera device
           advertises as fully supporting.</description>
           <details>
           A capability is a contract that the camera device makes in order
@@ -3806,7 +3964,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           * MANUAL_POST_PROCESSING
 
           Other capabilities may be available on either FULL or LIMITED
-          devices, but the application should query this field to be sure.
+          devices, but the application should query this key to be sure.
           </details>
           <hal_details>
           Additional constraint details per-capability will be available
@@ -3872,14 +4030,14 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
 
           <details>Attempting to get a key from a CaptureResult that is not
           listed here will always return a `null` value. Getting a key from
-          a CaptureResult that is listed here must never return a `null`
+          a CaptureResult that is listed here will generally never return a `null`
           value.
 
           The following keys may return `null` unless they are enabled:
 
           * android.statistics.lensShadingMap (non-null iff android.statistics.lensShadingMapMode == ON)
 
-          (Those sometimes-null keys should nevertheless be listed here
+          (Those sometimes-null keys will nevertheless be listed here
           if they are available.)
 
           This field can be used to query the feature set of a camera device
@@ -3918,7 +4076,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           details.
           </details>
           <hal_details>
-          Tags listed here must always have an entry in the static info metadata,
+          Keys listed here must always have an entry in the static info metadata,
           even if that size is 0 elements. Only array-type tags (e.g. lists,
           matrices, strings) are allowed to have 0 elements.
 
@@ -3944,11 +4102,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <array>
             <size>4</size>
           </array>
-          <description>The region of the sensor to read out for this capture.</description>
-          <units>(x,y) of top-left corner, width and height of region
-          in pixels; (0,0) is top-left corner of
+          <description>The desired region of the sensor to read out for this capture.</description>
+          <units>Pixel coordinates relative to
           android.sensor.info.activeArraySize</units>
           <details>
+            This control can be used to implement digital zoom.
+
             The crop region coordinate system is based off
             android.sensor.info.activeArraySize, with `(0, 0)` being the
             top-left corner of the sensor active array.
@@ -4105,7 +4264,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>The minimum frame duration that is supported
           for each resolution in android.scaler.availableJpegSizes.
           </description>
-          <units>ns</units>
+          <units>Nanoseconds</units>
           <range>TODO: Remove property.</range>
           <details>
           This corresponds to the minimum steady-state frame duration when only
@@ -4140,8 +4299,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               hwlevel="legacy">
           <description>The maximum ratio between both active area width
           and crop region width, and active area height and
-          crop region height.
-
+          crop region height, for android.scaler.cropRegion.
+          </description>
+          <units>Zoom scale factor</units>
+          <range>&amp;gt;=1</range>
+          <details>
           This represents the maximum amount of zooming possible by
           the camera device, or equivalently, the minimum cropping
           window size.
@@ -4149,8 +4311,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           Crop regions that have a width or height that is smaller
           than this ratio allows will be rounded up to the minimum
           allowed size by the camera device.
-          </description>
-          <range>&amp;gt;=1</range>
+          </details>
           <tag id="BC" />
         </entry>
         <entry name="availableProcessedMinDurations" type="int64" visibility="hidden" deprecated="true"
@@ -4162,8 +4323,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           android.scaler.availableProcessedSizes), this property lists the
           minimum supportable frame duration for that size.
           </description>
-          <units>ns</units>
-          <range>TODO: Remove property.</range>
+          <units>Nanoseconds</units>
           <details>
           This should correspond to the frame duration when only that processed
           stream is active, with all processing (typically in android.*.mode)
@@ -4184,7 +4344,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           processed output streams, such as YV12, NV12, and
           platform opaque YUV/RGB streams to the GPU or video
           encoders.</description>
-          <range>TODO: Remove property.</range>
           <details>
           The resolutions are listed as `(width, height)` pairs.
 
@@ -4224,8 +4383,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           android.scaler.availableRawSizes), this property lists the minimum
           supportable frame duration for that size.
           </description>
-          <units>ns</units>
-          <range>TODO: Remove property.</range>
+          <units>Nanoseconds</units>
           <details>
           Should correspond to the frame duration when only the raw stream is
           active.
@@ -4244,8 +4402,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>The resolutions available for use with raw
           sensor output streams, listed as width,
           height</description>
-          <range>TODO: Remove property.
-          Must include: - sensor maximum resolution.</range>
         </entry>
       </static>
       <dynamic>
@@ -4668,17 +4824,21 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         <entry name="exposureTime" type="int64" visibility="public" hwlevel="full">
           <description>Duration each pixel is exposed to
           light.</description>
-          <units>nanoseconds</units>
+          <units>Nanoseconds</units>
           <range>android.sensor.info.exposureTimeRange</range>
-          <details>If the sensor can't expose this exact duration, it should shorten the
+          <details>If the sensor can't expose this exact duration, it will shorten the
           duration exposed to the nearest possible value (rather than expose longer).
+          The final exposure time used will be available in the output capture result.
+
+          This control is only effective if android.control.aeMode or android.control.mode is set to
+          OFF; otherwise the auto-exposure algorithm will override this value.
           </details>
           <tag id="V1" />
         </entry>
         <entry name="frameDuration" type="int64" visibility="public" hwlevel="full">
           <description>Duration from start of frame exposure to
           start of next frame exposure.</description>
-          <units>nanoseconds</units>
+          <units>Nanoseconds</units>
           <range>See android.sensor.info.maxFrameDuration,
           android.scaler.streamConfigurationMap. The duration
           is capped to `max(duration, exposureTime + overhead)`.</range>
@@ -4756,6 +4916,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
 
           For more details about stalling, see
           StreamConfigurationMap#getOutputStallDuration(int,Size).
+
+          This control is only effective if android.control.aeMode or android.control.mode is set to
+          OFF; otherwise the auto-exposure algorithm will override this value.
           </details>
           <hal_details>
           For more details about stalling, see
@@ -4795,14 +4958,31 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <array>
               <size>4</size>
             </array>
-            <description>Area of raw data which corresponds to only
+            <description>The area of the image sensor which corresponds to
             active pixels.</description>
-            <range>This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be
-            &amp;gt;= `(0,0)`. The `(width, height)` must be &amp;lt;=
-            `android.sensor.info.pixelArraySize`.
+            <units>Pixel coordinates on the image sensor</units>
+            <range>
             </range>
-            <details>It is smaller or equal to
-            sensor full pixel array, which could include the black calibration pixels.</details>
+            <details>
+            This is the region of the sensor that actually receives light from the scene.
+            Therefore, the size of this region determines the maximum field of view and the maximum
+            number of pixels that an image from this sensor can contain.
+
+            The rectangle is defined in terms of the full pixel array; (0,0) is the top-left of the
+            full pixel array, and the size of the full pixel array is given by
+            android.sensor.info.pixelArraySize.
+
+            Most other keys listing pixel coordinates have their coordinate systems based on the
+            active array, with `(0, 0)` being the top-left of the active array rectangle.
+
+            The active array may be smaller than the full pixel array, since the full array may
+            include black calibration pixels or other inactive regions.
+            </details>
+            <hal_details>
+            This array contains `(xmin, ymin, width, height)`. The `(xmin, ymin)` must be
+            &amp;gt;= `(0,0)`.
+            The `(width, height)` must be &amp;lt;= `android.sensor.info.pixelArraySize`.
+            </hal_details>
             <tag id="RAW" />
           </entry>
           <entry name="sensitivityRange" type="int32" visibility="public"
@@ -4812,12 +4992,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <array>
               <size>2</size>
             </array>
-            <description>Range of valid sensitivities.</description>
+            <description>Range of sensitivities for android.sensor.sensitivity supported by this
+            camera device.</description>
             <range>Min &lt;= 100, Max &amp;gt;= 800</range>
             <details>
-              The minimum and maximum valid values for the
-              android.sensor.sensitivity control.
-
               The values are the standard ISO sensitivity values,
               as defined in ISO 12232:2006.
             </details>
@@ -4848,40 +5026,33 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <array>
               <size>2</size>
             </array>
-            <description>Range of valid exposure
-            times used by android.sensor.exposureTime.</description>
-            <range>Min &lt;= 100e3 (100 us). For FULL capability devices
-            (android.info.supportedHardwareLevel == FULL), Max SHOULD be
-            &amp;gt;= 1e9 (1sec), MUST be &amp;gt;= 100e6 (100ms)</range>
-            <details>The min value will be &lt;= 100e3 (100 us). For FULL
+            <description>The range of image exposure times for android.sensor.exposureTime supported
+            by this camera device.
+            </description>
+            <units>Nanoseconds</units>
+            <range>The minimum exposure time will be less than 100 us. For FULL
             capability devices (android.info.supportedHardwareLevel == FULL),
-            max will be &amp;gt;= 100e6 (100ms)</details>
+            the maximum exposure time will be greater than 100ms.</range>
             <hal_details>For FULL capability devices (android.info.supportedHardwareLevel == FULL),
-            The maximum of the range SHOULD be at least
-            1 second (1e9), MUST be at least 100ms.</hal_details>
+            The maximum of the range SHOULD be at least 1 second (1e9), MUST be at least
+            100ms.
+            </hal_details>
             <tag id="V1" />
           </entry>
           <entry name="maxFrameDuration" type="int64" visibility="public"
                  hwlevel="full">
-            <description>Maximum possible frame duration (minimum frame
-            rate).</description>
-            <units>nanoseconds</units>
+            <description>The maximum possible frame duration (minimum frame rate) for
+            android.sensor.frameDuration that is supported this camera device.</description>
+            <units>Nanoseconds</units>
             <range>For FULL capability devices
-            (android.info.supportedHardwareLevel == FULL), Max SHOULD be
-            &amp;gt;= 1e9 (1sec), MUST be &amp;gt;= 100e6 (100ms)
+            (android.info.supportedHardwareLevel == FULL), at least 100ms.
             </range>
-            <details>The largest possible android.sensor.frameDuration
-            that will be accepted by the camera device. Attempting to use
-            frame durations beyond the maximum will result in the frame duration
-            being clipped to the maximum. See that control
-            for a full definition of frame durations.
-
-            Refer to
-            StreamConfigurationMap#getOutputMinFrameDuration(int,Size)
-            for the minimum frame duration values.
+            <details>Attempting to use frame durations beyond the maximum will result in the frame
+            duration being clipped to the maximum. See that control for a full definition of frame
+            durations.
 
-            For FULL capability devices (android.info.supportedHardwareLevel == FULL),
-            max will be &amp;gt;= 100e6 (100ms).
+            Refer to StreamConfigurationMap#getOutputMinFrameDuration(int,Size) for the minimum
+            frame duration values.
             </details>
             <hal_details>
             For FULL capability devices (android.info.supportedHardwareLevel == FULL),
@@ -4904,13 +5075,14 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <tag id="V1" />
           </entry>
           <entry name="physicalSize" type="float" visibility="public"
-          type_notes="width x height in millimeters"
+          type_notes="width x height"
           container="array" typedef="sizeF" hwlevel="legacy">
             <array>
               <size>2</size>
             </array>
             <description>The physical dimensions of the full pixel
             array.</description>
+            <units>Millimeters</units>
             <details>This is the physical size of the sensor pixel
             array defined by android.sensor.info.pixelArraySize.
             </details>
@@ -4923,8 +5095,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <array>
               <size>2</size>
             </array>
-            <description>Dimensions of full pixel array, possibly
+            <description>Dimensions of the full pixel array, possibly
             including black calibration pixels.</description>
+            <units>Pixels</units>
             <details>The pixel count of the full pixel array,
             which covers android.sensor.info.physicalSize area.
 
@@ -4933,6 +5106,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             raw size listed in android.scaler.streamConfigurationMap.
             If a size corresponding to pixelArraySize is listed, the resulting
             raw sensor image will include black pixels.
+
+            Some parts of the full pixel array may not receive light from the scene,
+            or are otherwise inactive.  The android.sensor.info.activeArraySize key
+            defines the rectangle of active pixels that actually forms an image.
             </details>
             <tag id="RAW" />
             <tag id="BC" />
@@ -4947,7 +5124,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             sample values from the sensor.  This is typically caused by the
             sensor becoming highly non-linear or clipping. The minimum for
             each channel is specified by the offset in the
-            android.sensor.blackLevelPattern tag.
+            android.sensor.blackLevelPattern key.
 
             The white level is typically determined either by sensor bit depth
             (8-14 bits is expected), or by the point where the sensor response
@@ -5033,11 +5210,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           android.sensor.forwardMatrix1 matrices.
           </description>
           <details>
-          The values in this tag correspond to the values defined for the
+          The values in this key correspond to the values defined for the
           EXIF LightSource tag. These illuminants are standard light sources
           that are often used calibrating camera devices.
 
-          If this tag is present, then android.sensor.colorTransform1,
+          If this key is present, then android.sensor.colorTransform1,
           android.sensor.calibrationTransform1, and
           android.sensor.forwardMatrix1 will also be present.
 
@@ -5077,12 +5254,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           android.sensor.calibrationTransform2, and
           android.sensor.forwardMatrix2 matrices.
           </description>
+          <range>Any value listed in android.sensor.referenceIlluminant1</range>
           <details>
           See android.sensor.referenceIlluminant1 for more details.
-          Valid values for this are the same as those given for the first
-          reference illuminant.
 
-          If this tag is present, then android.sensor.colorTransform2,
+          If this key is present, then android.sensor.colorTransform2,
           android.sensor.calibrationTransform2, and
           android.sensor.forwardMatrix2 will also be present.
           </details>
@@ -5282,12 +5458,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           </description>
           <range>&amp;gt;= 0 for each.</range>
           <details>
-          This tag specifies the zero light value for each of the CFA mosaic
+          This key specifies the zero light value for each of the CFA mosaic
           channels in the camera sensor.  The maximal value output by the
           sensor is represented by the value in android.sensor.info.whiteLevel.
 
           The values are given in the same order as channels listed for the CFA
-          layout tag (see android.sensor.info.colorFilterArrangement), i.e. the
+          layout key (see android.sensor.info.colorFilterArrangement), i.e. the
           nth value given corresponds to the black level offset for the nth
           color channel listed in the CFA.
           </details>
@@ -5310,14 +5486,16 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         </entry>
         <entry name="orientation" type="int32" visibility="public"
                hwlevel="legacy">
-          <description>Clockwise angle through which the output
-          image needs to be rotated to be upright on the device
-          screen in its native orientation. Also defines the
-          direction of rolling shutter readout, which is from top
-          to bottom in the sensor's coordinate system</description>
-          <units>degrees clockwise rotation, only multiples of
+          <description>Clockwise angle through which the output image needs to be rotated to be
+          upright on the device screen in its native orientation.
+          </description>
+          <units>Degrees of clockwise rotation; always a multiple of
           90</units>
-          <range>0,90,180,270</range>
+          <range>0, 90, 180, 270</range>
+          <details>
+          Also defines the direction of rolling shutter readout, which is from top to bottom in
+          the sensor's coordinate system.
+          </details>
           <tag id="BC" />
         </entry>
         <entry name="profileHueSatMapDimensions" type="int32"
@@ -5356,7 +5534,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
                hwlevel="legacy">
           <description>Time at start of exposure of first
           row of the image sensor active array, in nanoseconds.</description>
-          <units>nanoseconds</units>
+          <units>Nanoseconds</units>
           <range>&amp;gt; 0</range>
           <details>The timestamps are also included in all image
           buffers produced for the same capture, and will be identical
@@ -5396,7 +5574,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           somewhere close to it.
           </description>
 
-          <units>celsius</units>
+          <units>Celsius</units>
           <range>Optional. This value is missing if no temperature is available.</range>
           <tag id="FUTURE" />
         </entry>
@@ -5431,10 +5609,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           Noise model coefficients for each CFA mosaic channel.
           </description>
           <details>
-          This tag contains two noise model coefficients for each CFA channel
+          This key contains two noise model coefficients for each CFA channel
           corresponding to the sensor amplification (S) and sensor readout
           noise (O).  These are given as pairs of coefficients for each channel
-          in the same order as channels listed for the CFA layout tag
+          in the same order as channels listed for the CFA layout key
           (see android.sensor.info.colorFilterArrangement).  This is
           represented as an array of Pair&amp;lt;Double, Double&amp;gt;, where
           the first member of the Pair at index n is the S coefficient and the
@@ -5476,8 +5654,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           for each pixel.
           </description>
           <units>
-          Hue shift is given in degrees; saturation and value scale factors are
-          unitless.
+          The hue shift is given in degrees; saturation and value scale factors are
+          unitless and are between 0 and 1 inclusive
           </units>
           <details>
           hue_samples, saturation_samples, and value_samples are given in
@@ -5485,7 +5663,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
 
           Each entry of this map contains three floats corresponding to the
           hue shift, saturation scale, and value scale, respectively; where the
-          hue shift has the lowest index. The map entries are stored in the tag
+          hue shift has the lowest index. The map entries are stored in the key
           in nested loop order, with the value divisions in the outer loop, the
           hue divisions in the middle loop, and the saturation divisions in the
           inner loop. All zero input saturation entries are required to have a
@@ -5510,7 +5688,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           sample is required to be `(1, 1)`.
           </range>
           <details>
-          This tag contains a default tone curve that can be applied while
+          This key contains a default tone curve that can be applied while
           processing the image as a starting point for user adjustments.
           The curve is specified as a list of value pairs in linear gamma.
           The curve is interpolated using a cubic spline.
@@ -5576,9 +5754,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             A pixel `[R, G_even, G_odd, B]` that supplies the test pattern
             when android.sensor.testPatternMode is SOLID_COLOR.
           </description>
-          <range>Optional.
-          Must be supported if android.sensor.availableTestPatternModes contains
-          SOLID_COLOR.</range>
           <details>
           Each color channel is treated as an unsigned 32-bit integer.
           The camera device then uses the most significant X bits
@@ -5703,8 +5878,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>When enabled, the sensor sends a test pattern instead of
           doing a real exposure from the camera.
           </description>
-          <range>Optional. Defaults to OFF. Value must be one of
-          android.sensor.availableTestPatternModes</range>
+          <range>android.sensor.availableTestPatternModes</range>
           <details>
           When a test pattern is enabled, all manual sensor controls specified
           by android.sensor.* will be ignored. All other controls should
@@ -5713,6 +5887,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           For example, if manual flash is enabled, flash firing should still
           occur (and that the test pattern remain unmodified, since the flash
           would not actually affect it).
+
+          Defaults to OFF.
           </details>
           <hal_details>
           All test patterns are specified in the Bayer domain.
@@ -5736,25 +5912,30 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <array>
             <size>n</size>
           </array>
-          <description>Lists the supported sensor test pattern modes for android.sensor.testPatternMode.
+          <description>List of sensor test pattern modes for android.sensor.testPatternMode
+          supported by this camera device.
           </description>
-          <range>Always includes OFF if defined. All custom modes must be >= CUSTOM1</range>
+          <range>Any value listed in android.sensor.testPatternMode</range>
           <details>
-            Optional. Defaults to [OFF].
+            Defaults to OFF, and always includes OFF if defined.
           </details>
+          <hal_details>
+            All custom modes must be >= CUSTOM1.
+          </hal_details>
         </entry>
       </static>
       <dynamic>
         <entry name="rollingShutterSkew" type="int64" visibility="public" hwlevel="limited">
           <description>Duration between the start of first row exposure
           and the start of last row exposure.</description>
-          <units>nanoseconds</units>
+          <units>Nanoseconds</units>
           <range> &amp;gt;= 0 and &amp;lt;
           StreamConfigurationMap#getOutputMinFrameDuration(int, Size).</range>
           <details>
-          This is the exposure time skew (in the unit of nanosecond) between the first and
-          last row exposure start times. The first row and the last row are the first
-          and last rows inside of the android.sensor.info.activeArraySize.
+          This is the exposure time skew between the first and last
+          row exposure start times. The first row and the last row are
+          the first and last rows inside of the
+          android.sensor.info.activeArraySize.
 
           For typical camera sensors that use rolling shutters, this is also equivalent
           to the frame readout time.
@@ -5786,29 +5967,28 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           When set to OFF mode, no lens shading correction will be applied by the
           camera device, and an identity lens shading map data will be provided
           if `android.statistics.lensShadingMapMode == ON`. For example, for lens
-          shading map with size specified as `android.lens.info.shadingMapSize = [ 4, 3 ]`,
-          the output android.statistics.lensShadingMap for this case will be an identity map
-          shown below:
+          shading map with size of `[ 4, 3 ]`,
+          the output android.statistics.lensShadingCorrectionMap for this case will be an identity
+          map shown below:
 
               [ 1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-                  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-                1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-                  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
-                1.0, 1.0, 1.0, 1.0,   1.0, 1.0, 1.0, 1.0,
-                  1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0 ]
-
-          When set to other modes, lens shading correction will be applied by the
-          camera device. Applications can request lens shading map data by setting
-          android.statistics.lensShadingMapMode to ON, and then the camera device will provide
-          lens shading map data in android.statistics.lensShadingMap, with size specified
-          by android.lens.info.shadingMapSize; the returned shading map data will be the one
-          applied by the camera device for this capture request.
-
-          The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability
-          of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
-          AUTO modes(android.control.aeMode `!=` OFF and android.control.awbMode `!=` OFF),
-          to get best results, it is recommended that the applications wait for the AE and AWB to
-          be converged before using the returned shading map data.
+               1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+               1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+               1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+               1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0,
+               1.0, 1.0, 1.0, 1.0,  1.0, 1.0, 1.0, 1.0 ]
+
+          When set to other modes, lens shading correction will be applied by the camera
+          device. Applications can request lens shading map data by setting
+          android.statistics.lensShadingMapMode to ON, and then the camera device will provide lens
+          shading map data in android.statistics.lensShadingCorrectionMap; the returned shading map
+          data will be the one applied by the camera device for this capture request.
+
+          The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore
+          the reliability of the map data may be affected by the AE and AWB algorithms. When AE and
+          AWB are in AUTO modes(android.control.aeMode `!=` OFF and android.control.awbMode `!=`
+          OFF), to get best results, it is recommended that the applications wait for the AE and AWB
+          to be converged before using the returned shading map data.
           </details>
         </entry>
         <entry name="strength" type="byte">
@@ -5834,29 +6014,26 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             results.</notes></value>
             <value optional="true">SIMPLE
             <notes>Return face rectangle and confidence values only.
-
-            In this mode, only android.statistics.faceRectangles and
-            android.statistics.faceScores outputs are valid.
             </notes></value>
             <value optional="true">FULL
             <notes>Return all face
             metadata.
 
-            In this mode,
-            android.statistics.faceRectangles,
-            android.statistics.faceScores,
-            android.statistics.faceIds, and
-            android.statistics.faceLandmarks outputs are valid.
+            In this mode, face rectangles, scores, landmarks, and face IDs are all valid.
             </notes></value>
           </enum>
-          <description>Control for the face detector
+          <description>Operating mode for the face detector
           unit.</description>
-          <range>
-          android.statistics.info.availableFaceDetectModes</range>
+          <range>android.statistics.info.availableFaceDetectModes</range>
           <details>Whether face detection is enabled, and whether it
           should output just the basic fields or the full set of
-          fields. Value must be one of the
-          android.statistics.info.availableFaceDetectModes.</details>
+          fields.</details>
+          <hal_details>
+            SIMPLE mode must fill in android.statistics.faceRectangles and
+            android.statistics.faceScores.
+            FULL mode must also fill in android.statistics.faceIds, and
+            android.statistics.faceLandmarks.
+          </hal_details>
           <tag id="BC" />
         </entry>
         <entry name="histogramMode" type="byte" enum="true" typedef="boolean">
@@ -5888,13 +6065,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             </notes></value>
           </enum>
           <description>
-          Operating mode for hotpixel map generation.
+          Operating mode for hot pixel map generation.
           </description>
+          <range>android.statistics.info.availableHotPixelMapModes</range>
           <details>
-          If set to ON, a hotpixel map is returned in android.statistics.hotPixelMap.
-          If set to OFF, no hotpixel map will be returned.
-
-          This must be set to a valid mode from android.statistics.info.availableHotPixelMapModes.
+          If set to `true`, a hot pixel map is returned in android.statistics.hotPixelMap.
+          If set to `false`, no hot pixel map will be returned.
           </details>
           <tag id="V1" />
           <tag id="RAW" />
@@ -5911,22 +6087,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <array>
               <size>n</size>
             </array>
-            <description>The face detection modes that are available
-            for this camera device.
+            <description>List of face detection modes for android.statistics.faceDetectMode that are
+            supported by this camera device.
             </description>
-            <units>List of enum:
-            OFF
-            SIMPLE
-            FULL</units>
+            <range>Any value listed in android.statistics.faceDetectMode</range>
             <details>OFF is always supported.
-
-            SIMPLE means the device supports the
-            android.statistics.faceRectangles and
-            android.statistics.faceScores outputs.
-
-            FULL means the device additionally supports the
-            android.statistics.faceIds and
-            android.statistics.faceLandmarks outputs.
             </details>
           </entry>
           <entry name="histogramBucketCount" type="int32">
@@ -5969,16 +6134,15 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               <size>n</size>
             </array>
             <description>
-            The set of hot pixel map output modes supported by this camera device.
+            List of hot pixel map output modes for android.statistics.hotPixelMapMode that are
+            supported by this camera device.
             </description>
+            <range>Any value listed in android.statistics.hotPixelMapMode</range>
             <details>
-            This tag lists valid output modes for android.statistics.hotPixelMapMode.
-
-            If no hotpixel map is available for this camera device, this will contain
-            only OFF.  If the hotpixel map is available, this will include both
-            the ON and OFF options.
+            If no hotpixel map output is available for this camera device, this will contain only
+            `false`.
 
-            Required on devices with the RAW capability.
+            ON is always supported on devices with the RAW capability.
             </details>
             <tag id="V1" />
             <tag id="RAW" />
@@ -6055,7 +6219,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>List of the faces detected through camera face detection
-          in this result.</description>
+          in this capture.</description>
           <details>
           Only available if android.statistics.faceDetectMode `!=` OFF.
           </details>
@@ -6357,7 +6521,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           android.statistics.lensShadingMap will be provided in
           the output result metadata.
 
-          Required for devices with the RAW capability.
+          ON is always supported on devices with the RAW capability.
           </details>
           <tag id="RAW" />
         </entry>
@@ -6379,8 +6543,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>Tonemapping / contrast / gamma curve for the blue
           channel, to use when android.tonemap.mode is
           CONTRAST_CURVE.</description>
-          <units>same as android.tonemap.curveRed</units>
-          <range>same as android.tonemap.curveRed</range>
           <details>See android.tonemap.curveRed for more details.</details>
         </entry>
         <entry name="curveGreen" type="float" visibility="hidden"
@@ -6393,8 +6555,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>Tonemapping / contrast / gamma curve for the green
           channel, to use when android.tonemap.mode is
           CONTRAST_CURVE.</description>
-          <units>same as android.tonemap.curveRed</units>
-          <range>same as android.tonemap.curveRed</range>
           <details>See android.tonemap.curveRed for more details.</details>
         </entry>
         <entry name="curveRed" type="float" visibility="hidden"
@@ -6417,8 +6577,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
                 [ P0in, P0out, P1in, P1out, P2in, P2out, P3in, P3out, ..., PNin, PNout ]
               2 &lt;= N &lt;= android.tonemap.maxCurvePoints
 
-          These are sorted in order of increasing `Pin`; it is always
-          guaranteed that input values 0.0 and 1.0 are included in the list to
+          These are sorted in order of increasing `Pin`; it is
+          required that input values 0.0 and 1.0 are included in the list to
           define a complete mapping. For input values between control points,
           the camera device must linearly interpolate between the control
           points.
@@ -6569,6 +6729,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           </enum>
           <description>High-level global contrast/gamma/tonemapping control.
           </description>
+          <range>android.tonemap.availableToneMapModes</range>
           <details>
           When switching to an application-defined contrast curve by setting
           android.tonemap.mode to CONTRAST_CURVE, the curve is defined
@@ -6583,9 +6744,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           transforms will be disabled when android.tonemap.mode is
           CONTRAST_CURVE.
 
-          This must be set to a valid mode in
-          android.tonemap.availableToneMapModes.
-
           When using either FAST or HIGH_QUALITY, the camera device will
           emit its own tonemap curve in android.tonemap.curve.
           These values are always available, and as close as possible to the
@@ -6602,12 +6760,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>Maximum number of supported points in the
             tonemap curve that can be used for android.tonemap.curve.
           </description>
-          <range>&amp;gt;= 64</range>
           <details>
-          If the actual number of points provided by the application (in
-          android.tonemap.curve*)  is less than max, the camera device will
-          resample the curve to its internal representation, using linear
-          interpolation.
+          If the actual number of points provided by the application (in android.tonemap.curve*) is
+          less than this maximum, the camera device will resample the curve to its internal
+          representation, using linear interpolation.
 
           The output curves in the result metadata may have a different number
           of points than the input curves, and will represent the actual
@@ -6623,13 +6779,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>
-          The set of tonemapping modes supported by this camera device.
+          List of tonemapping modes for android.tonemap.mode that are supported by this camera
+          device.
           </description>
+          <range>Any value listed in android.tonemap.mode</range>
           <details>
-          This tag lists the valid modes for android.tonemap.mode.
-
-          Full-capability camera devices must always support CONTRAST_CURVE and
-          FAST.
+          Camera devices that support the MANUAL_POST_PROCESSING capability will always list
+          CONTRAST_CURVE and FAST. This includes all FULL level devices.
           </details>
         </entry>
       </static>
@@ -6716,11 +6872,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>
           Generally classifies the overall set of the camera device functionality.
           </description>
-          <range>Default value is LIMITED.</range>
           <details>
           Camera devices will come in three flavors: LEGACY, LIMITED and FULL.
 
-          A FULL device has the most support possible and will support below capabilities:
+          A FULL device will support below capabilities:
 
           * 30fps at maximum resolution (== sensor resolution) is preferred, more than 20fps is required.
           * Per frame control (android.sync.maxLatency `==` PER_FRAME_CONTROL)
@@ -6735,6 +6890,16 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           A LIMITED device may have some or none of the above characteristics.
           To find out more refer to android.request.availableCapabilities.
 
+          Some features are not part of any particular hardware level or capability and must be
+          queried separately. These include:
+
+          * Calibrated timestamps (android.sensor.info.timestampSource `==` REALTIME)
+          * Precision lens control (android.lens.info.focusDistanceCalibration `==` CALIBRATED)
+          * Face detection (android.statistics.info.availableFaceDetectModes)
+          * Optical or electrical image stabilization
+            (android.lens.info.availableOpticalStabilization,
+             android.control.availableVideoStabilizationModes)
+
           A LEGACY device does not support per-frame control, manual sensor control, manual
           post-processing, arbitrary cropping regions, and has relaxed performance constraints.
 
@@ -6769,9 +6934,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           </enum>
           <description> Whether black-level compensation is locked
           to its current values, or is free to vary.</description>
-          <details>When set to ON, the values used for black-level
+          <details>When set to `true` (ON), the values used for black-level
           compensation will not change until the lock is set to
-          OFF.
+          `false` (OFF).
 
           Since changes to certain capture parameters (such as
           exposure time) may require resetting of black level
@@ -6979,8 +7144,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           result's state becomes synchronized (by setting
           android.sync.frameNumber to a non-negative value).
           </description>
-          <units>number of processed requests</units>
-          <range>&amp;gt;= -1</range>
+          <units>Frame counts</units>
+          <range>A positive value, PER_FRAME_CONTROL, or UNKNOWN.</range>
           <details>
           This defines the maximum distance (in number of metadata results),
           between android.sync.frameNumber and the equivalent