Merge "Camera: clarify lens shading map" into nyc-dev

diff --combined camera/docs/docs.html
index a8f886c,cac793c..fcb399d
--- 1/camera/docs/docs.html
--- 2/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@@ -4181,7 -4181,7 +4181,7 @@@ both at the same time.<wbr/></p
              </td> <!-- entry_type -->
  
              <td class="entry_description">
 -              <p>The amount of additional sesnsitivity boost applied to output images
 +              <p>The amount of additional sensitivity boost applied to output images
  after RAW sensor data is captured.<wbr/></p>
              </td>
  
@@@ -4206,10 -4206,10 +4206,10 @@@
  camera processing pipeline after sensor RAW image is captured.<wbr/>
  Such a boost will be applied to YUV/<wbr/>JPEG format output images but will not
  have effect on RAW output formats like RAW_<wbr/>SENSOR,<wbr/> RAW10,<wbr/> RAW12 or RAW_<wbr/>OPAQUE.<wbr/></p>
 -<p>This key is optional.<wbr/> Applications can assume there is no boost applied
 -after RAW is captured if this key is not available.<wbr/>
 -When this key is available,<wbr/> the sensitivity boost value must be within
 -<a href="#static_android.control.postRawSensitivityBoostRange">android.<wbr/>control.<wbr/>post<wbr/>Raw<wbr/>Sensitivity<wbr/>Boost<wbr/>Range</a>.<wbr/></p>
 +<p>This key will be <code>null</code> for devices that do not support any RAW format
 +outputs.<wbr/> For devices that do support RAW format outputs,<wbr/> this key will always
 +present,<wbr/> and if a device does not support post RAW sensitivity boost,<wbr/> it will
 +list <code>100</code> in this key.<wbr/></p>
  <p>If the camera device cannot apply the exact boost requested,<wbr/> it will reduce the
  boost to the nearest supported value.<wbr/>
  The final boost value used will be available in the output capture result.<wbr/></p>
@@@ -8827,7 -8827,7 +8827,7 @@@ both at the same time.<wbr/></p
              </td> <!-- entry_type -->
  
              <td class="entry_description">
 -              <p>The amount of additional sesnsitivity boost applied to output images
 +              <p>The amount of additional sensitivity boost applied to output images
  after RAW sensor data is captured.<wbr/></p>
              </td>
  
@@@ -8852,10 -8852,10 +8852,10 @@@
  camera processing pipeline after sensor RAW image is captured.<wbr/>
  Such a boost will be applied to YUV/<wbr/>JPEG format output images but will not
  have effect on RAW output formats like RAW_<wbr/>SENSOR,<wbr/> RAW10,<wbr/> RAW12 or RAW_<wbr/>OPAQUE.<wbr/></p>
 -<p>This key is optional.<wbr/> Applications can assume there is no boost applied
 -after RAW is captured if this key is not available.<wbr/>
 -When this key is available,<wbr/> the sensitivity boost value must be within
 -<a href="#static_android.control.postRawSensitivityBoostRange">android.<wbr/>control.<wbr/>post<wbr/>Raw<wbr/>Sensitivity<wbr/>Boost<wbr/>Range</a>.<wbr/></p>
 +<p>This key will be <code>null</code> for devices that do not support any RAW format
 +outputs.<wbr/> For devices that do support RAW format outputs,<wbr/> this key will always
 +present,<wbr/> and if a device does not support post RAW sensitivity boost,<wbr/> it will
 +list <code>100</code> in this key.<wbr/></p>
  <p>If the camera device cannot apply the exact boost requested,<wbr/> it will reduce the
  boost to the nearest supported value.<wbr/>
  The final boost value used will be available in the output capture result.<wbr/></p>
@@@ -23608,8 -23608,8 +23608,8 @@@ image of a gray wall (using bicubic int
  
              <td class="entry_description">
                <p>The shading map is a low-resolution floating-point map
- that lists the coefficients used to correct for vignetting,<wbr/> for each
- Bayer color channel of RAW image data.<wbr/></p>
+ that lists the coefficients used to correct for vignetting and color shading,<wbr/>
+ for each Bayer color channel of RAW image data.<wbr/></p>
              </td>
  
              <td class="entry_units">
@@@ -23628,8 -23628,18 +23628,18 @@@
            </tr>
            <tr class="entry_cont">
              <td class="entry_details" colspan="5">
-               <p>The least shaded section of the image should have a gain factor
- of 1; all other sections should have gains above 1.<wbr/></p>
+               <p>The lens shading correction is defined as a full shading correction that
+ corrects both color shading for the output non-RAW images.<wbr/> After the
+ shading map is applied,<wbr/> the output non-RAW images will be flat-field images
+ for flat scenes under uniform illumination.<wbr/></p>
+ <p>When there is no lens shading correction applied to RAW output images
+ (<a href="#static_android.sensor.info.lensShadingApplied">android.<wbr/>sensor.<wbr/>info.<wbr/>lens<wbr/>Shading<wbr/>Applied</a> <code>==</code> false),<wbr/> this map is a full lens
+ shading correction map; when there is some lens shading correction applied
+ to the RAW output image (<a href="#static_android.sensor.info.lensShadingApplied">android.<wbr/>sensor.<wbr/>info.<wbr/>lens<wbr/>Shading<wbr/>Applied</a> <code>==</code> true),<wbr/>
+ this map reports the remaining lens shading correction map that needs to be
+ applied to get fully shading corrected images.<wbr/></p>
+ <p>For a full shading correction map,<wbr/> the least shaded section of the image
+ should have a gain factor of 1; all other sections should have gains above 1.<wbr/></p>
  <p>When <a href="#controls_android.colorCorrection.mode">android.<wbr/>color<wbr/>Correction.<wbr/>mode</a> = TRANSFORM_<wbr/>MATRIX,<wbr/> the map
  must take into account the colorCorrection settings.<wbr/></p>
  <p>The shading map is for the entire active pixel array,<wbr/> and is not

diff --combined camera/docs/metadata_properties.xml
index e0a1737,a878534..b216851
--- 1/camera/docs/metadata_properties.xml
--- 2/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@@ -2758,7 -2758,7 +2758,7 @@@ xsi:schemaLocation="http://schemas.andr
        </static>
        <controls>
          <entry name="postRawSensitivityBoost" type="int32" visibility="public">
 -          <description>The amount of additional sesnsitivity boost applied to output images
 +          <description>The amount of additional sensitivity boost applied to output images
               after RAW sensor data is captured.
            </description>
            <units>ISO arithmetic units, the same as android.sensor.sensitivity</units>
@@@ -2769,10 -2769,10 +2769,10 @@@
            Such a boost will be applied to YUV/JPEG format output images but will not
            have effect on RAW output formats like RAW_SENSOR, RAW10, RAW12 or RAW_OPAQUE.
  
 -          This key is optional. Applications can assume there is no boost applied
 -          after RAW is captured if this key is not available.
 -          When this key is available, the sensitivity boost value must be within
 -          android.control.postRawSensitivityBoostRange.
 +          This key will be `null` for devices that do not support any RAW format
 +          outputs. For devices that do support RAW format outputs, this key will always
 +          present, and if a device does not support post RAW sensitivity boost, it will
 +          list `100` in this key.
  
            If the camera device cannot apply the exact boost requested, it will reduce the
            boost to the nearest supported value.
@@@ -7680,11 -7680,24 +7680,24 @@@
              <size>m</size>
            </array>
            <description>The shading map is a low-resolution floating-point map
-           that lists the coefficients used to correct for vignetting, for each
-           Bayer color channel of RAW image data.</description>
+           that lists the coefficients used to correct for vignetting and color shading,
+           for each Bayer color channel of RAW image data.</description>
            <range>Each gain factor is &amp;gt;= 1</range>
-           <details>The least shaded section of the image should have a gain factor
-           of 1; all other sections should have gains above 1.
+           <details>
+           The lens shading correction is defined as a full shading correction that
+           corrects both color shading for the output non-RAW images. After the
+           shading map is applied, the output non-RAW images will be flat-field images
+           for flat scenes under uniform illumination.
+ 
+           When there is no lens shading correction applied to RAW output images
+           (android.sensor.info.lensShadingApplied `==` false), this map is a full lens
+           shading correction map; when there is some lens shading correction applied
+           to the RAW output image (android.sensor.info.lensShadingApplied `==` true),
+           this map reports the remaining lens shading correction map that needs to be
+           applied to get fully shading corrected images.
+ 
+           For a full shading correction map, the least shaded section of the image
+           should have a gain factor of 1; all other sections should have gains above 1.
  
            When android.colorCorrection.mode = TRANSFORM_MATRIX, the map
            must take into account the colorCorrection settings.