camera_metadata: Update focus distance related tags.

Also add focus distance calibration tag.

Change-Id: Iab8f626ec8d1166cfa78ec04425813a3aec9a4c7

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 3491d93..5ce4948 100644 (file)
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -346,6 +346,7 @@
             <li><a href="#static_android.lens.info.hyperfocalDistance">android.lens.info.hyperfocalDistance</a></li>
             <li><a href="#static_android.lens.info.minimumFocusDistance">android.lens.info.minimumFocusDistance</a></li>
             <li><a href="#static_android.lens.info.shadingMapSize">android.lens.info.shadingMapSize</a></li>
+            <li><a href="#static_android.lens.info.focusDistanceCalibration">android.lens.info.focusDistanceCalibration</a></li>
 
             <li><a href="#static_android.lens.facing">android.lens.facing</a></li>
             <li><a href="#static_android.lens.opticalAxisAngle">android.lens.opticalAxisAngle</a></li>
@@ -7097,7 +7098,7 @@ measured from frontmost surface of the lens</p>
             </td>
 
             <td class="entry_units">
-              diopters (1/<wbr/>m)
+              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
             </td>
 
             <td class="entry_range">
@@ -7541,12 +7542,11 @@ map</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>Hyperfocal distance for this lens; set to
-0 if fixed focus</p>
+              <p>Optional.<wbr/> Hyperfocal distance for this lens.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              diopters
+              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
             </td>
 
             <td class="entry_range">
@@ -7554,9 +7554,6 @@ map</p>
             </td>
 
             <td class="entry_tags">
-              <ul class="entry_tags">
-                  <li><a href="#tag_BC">BC</a></li>
-              </ul>
             </td>
 
           </tr>
@@ -7565,8 +7562,9 @@ map</p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>The hyperfocal distance is used for the old
-API's 'fixed' setting</p>
+              <p>If the lens is fixed focus,<wbr/> the camera device will report 0.<wbr/></p>
+<p>If the lens is not fixed focus,<wbr/> the camera device will report this
+field when <a href="#static_android.lens.info.focusDistanceCalibration">android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration</a> is APPROXIMATE or CALIBRATED.<wbr/></p>
             </td>
           </tr>
 
@@ -7589,11 +7587,11 @@ API's 'fixed' setting</p>
 
             <td class="entry_description">
               <p>Shortest distance from frontmost surface
-of the lens that can be focused correctly</p>
+of the lens that can be focused correctly.<wbr/></p>
             </td>
 
             <td class="entry_units">
-              diopters
+              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
             </td>
 
             <td class="entry_range">
@@ -7613,7 +7611,7 @@ of the lens that can be focused correctly</p>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
               <p>If the lens is fixed-focus,<wbr/> this should be
-0</p>
+0.<wbr/></p>
             </td>
           </tr>
 
@@ -7671,6 +7669,80 @@ must be smaller than 64x64.<wbr/></p>
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
            <!-- end of entry -->
         
+                
+          <tr class="entry" id="static_android.lens.info.focusDistanceCalibration">
+            <td class="entry_name" rowspan="3">
+              android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration
+            </td>
+            <td class="entry_type">
+                <span class="entry_type_name entry_type_name_enum">byte</span>
+
+              <span class="entry_type_visibility"> [public]</span>
+
+                <ul class="entry_type_enum">
+                  <li>
+                    <span class="entry_type_enum_name">UNCALIBRATED</span>
+                    <span class="entry_type_enum_notes"><p>The lens focus distance is not accurate,<wbr/> and the units used for
+<a href="#controls_android.lens.focusDistance">android.<wbr/>lens.<wbr/>focus<wbr/>Distance</a> do not correspond to any physical units.<wbr/>
+Setting the lens to the same focus distance on separate occasions may
+result in a different real focus distance,<wbr/> depending on factors such
+as the orientation of the device,<wbr/> the age of the focusing mechanism,<wbr/>
+and the device temperature.<wbr/> The focus distance value will still be
+in the range of <code>[0,<wbr/> <a href="#static_android.lens.info.minimumFocusDistance">android.<wbr/>lens.<wbr/>info.<wbr/>minimum<wbr/>Focus<wbr/>Distance</a>]</code>,<wbr/> where 0
+represents the farthest focus.<wbr/></p></span>
+                  </li>
+                  <li>
+                    <span class="entry_type_enum_name">APPROXIMATE</span>
+                    <span class="entry_type_enum_notes"><p>The lens focus distance is measured in diopters.<wbr/> However,<wbr/> setting the lens
+to the same focus distance on separate occasions may result in a
+different real focus distance,<wbr/> depending on factors such as the
+orientation of the device,<wbr/> the age of the focusing mechanism,<wbr/> and
+the device temperature.<wbr/></p></span>
+                  </li>
+                  <li>
+                    <span class="entry_type_enum_name">CALIBRATED</span>
+                    <span class="entry_type_enum_notes"><p>The lens focus distance is measured in diopters.<wbr/> The lens mechanism is
+calibrated so that setting the same focus distance is repeatable on
+multiple occasions with good accuracy,<wbr/> and the focus distance corresponds
+to the real physical distance to the plane of best focus.<wbr/></p></span>
+                  </li>
+                </ul>
+
+            </td> <!-- entry_type -->
+
+            <td class="entry_description">
+              <p>The lens focus distance calibration quality.<wbr/></p>
+            </td>
+
+            <td class="entry_units">
+            </td>
+
+            <td class="entry_range">
+            </td>
+
+            <td class="entry_tags">
+              <ul class="entry_tags">
+                  <li><a href="#tag_V1">V1</a></li>
+              </ul>
+            </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 lens focus distance calibration quality determines the reliability of
+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>
+            </td>
+          </tr>
+
+
+          <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
+           <!-- end of entry -->
+        
         
         
 
@@ -8031,7 +8103,7 @@ measured from frontmost surface of the lens</p>
             </td>
 
             <td class="entry_units">
-              diopters (1/<wbr/>m)
+              See android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
             </td>
 
             <td class="entry_range">
@@ -8083,7 +8155,7 @@ sharp focus (depth of field)</p>
 
             <td class="entry_units">
               pair of focus distances in diopters: (near,<wbr/>
-          far)
+          far),<wbr/> see android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration for details.<wbr/>
             </td>
 
             <td class="entry_range">
@@ -15593,7 +15665,6 @@ to know when sensor settings have been applied.<wbr/></p>
           <li><a href="#static_android.jpeg.availableThumbnailSizes">android.jpeg.availableThumbnailSizes</a> (static)</li>
           <li><a href="#controls_android.lens.focusDistance">android.lens.focusDistance</a> (controls)</li>
           <li><a href="#static_android.lens.info.availableFocalLengths">android.lens.info.availableFocalLengths</a> (static)</li>
-          <li><a href="#static_android.lens.info.hyperfocalDistance">android.lens.info.hyperfocalDistance</a> (static)</li>
           <li><a href="#dynamic_android.lens.focusRange">android.lens.focusRange</a> (dynamic)</li>
           <li><a href="#static_android.request.maxNumOutputStreams">android.request.maxNumOutputStreams</a> (static)</li>
           <li><a href="#controls_android.scaler.cropRegion">android.scaler.cropRegion</a> (controls)</li>
@@ -15641,6 +15712,7 @@ to know when sensor settings have been applied.<wbr/></p>
           <li><a href="#static_android.lens.info.geometricCorrectionMapSize">android.lens.info.geometricCorrectionMapSize</a> (static)</li>
           <li><a href="#static_android.lens.info.minimumFocusDistance">android.lens.info.minimumFocusDistance</a> (static)</li>
           <li><a href="#static_android.lens.info.shadingMapSize">android.lens.info.shadingMapSize</a> (static)</li>
+          <li><a href="#static_android.lens.info.focusDistanceCalibration">android.lens.info.focusDistanceCalibration</a> (static)</li>
           <li><a href="#static_android.lens.position">android.lens.position</a> (static)</li>
           <li><a href="#dynamic_android.lens.state">android.lens.state</a> (dynamic)</li>
           <li><a href="#controls_android.noiseReduction.mode">android.noiseReduction.mode</a> (controls)</li>

diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index ae97f5b..4b24d31 100644 (file)
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -2008,7 +2008,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         <entry name="focusDistance" type="float" visibility="public">
           <description>Distance to plane of sharpest focus,
           measured from frontmost surface of the lens</description>
-          <units>diopters (1/m)</units>
+          <units>See android.lens.info.focusDistanceCalibration for details.</units>
           <range>&amp;gt;= 0</range>
           <details>0 means infinity focus. Used value will be clamped
           to [0, android.lens.info.minimumFocusDistance].
@@ -2155,22 +2155,23 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <range>Both values &amp;gt;= 2</range>
             <tag id="V1" />
           </entry>
-          <entry name="hyperfocalDistance" type="float" visibility="public">
-            <description>Hyperfocal distance for this lens; set to
-            0 if fixed focus</description>
-            <units>diopters</units>
+          <entry name="hyperfocalDistance" type="float" visibility="public" optional="true">
+            <description>Optional. Hyperfocal distance for this lens.</description>
+            <units>See android.lens.info.focusDistanceCalibration for details.</units>
             <range>&amp;gt;= 0</range>
-            <details>The hyperfocal distance is used for the old
-            API's 'fixed' setting</details>
-            <tag id="BC" />
+            <details>If the lens is fixed focus, the camera device will report 0.
+
+            If the lens is not fixed focus, the camera device will report this
+            field when android.lens.info.focusDistanceCalibration is APPROXIMATE or CALIBRATED.
+            </details>
           </entry>
           <entry name="minimumFocusDistance" type="float" visibility="public">
             <description>Shortest distance from frontmost surface
-            of the lens that can be focused correctly</description>
-            <units>diopters</units>
+            of the lens that can be focused correctly.</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
-            0</details>
+            0.</details>
             <tag id="V1" />
           </entry>
           <entry name="shadingMapSize" type="int32" visibility="public"
@@ -2187,6 +2188,47 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             </details>
             <tag id="V1" />
           </entry>
+          <entry name="focusDistanceCalibration" type="byte" visibility="public" enum="true">
+            <enum>
+              <value>UNCALIBRATED
+                <notes>
+                The lens focus distance is not accurate, and the units used for
+                android.lens.focusDistance do not correspond to any physical units.
+                Setting the lens to the same focus distance on separate occasions may
+                result in a different real focus distance, depending on factors such
+                as the orientation of the device, the age of the focusing mechanism,
+                and the device temperature. The focus distance value will still be
+                in the range of `[0, android.lens.info.minimumFocusDistance]`, where 0
+                represents the farthest focus.
+                </notes>
+              </value>
+              <value>APPROXIMATE
+                <notes>
+                The lens focus distance is measured in diopters. However, setting the lens
+                to the same focus distance on separate occasions may result in a
+                different real focus distance, depending on factors such as the
+                orientation of the device, the age of the focusing mechanism, and
+                the device temperature.
+                </notes>
+              </value>
+              <value>CALIBRATED
+                <notes>
+                The lens focus distance is measured in diopters. The lens mechanism is
+                calibrated so that setting the same focus distance is repeatable on
+                multiple occasions with good accuracy, and the focus distance corresponds
+                to the real physical distance to the plane of best focus.
+                </notes>
+              </value>
+            </enum>
+            <description>The lens focus distance calibration quality.</description>
+            <details>
+            The lens focus distance calibration quality determines the reliability of
+            focus related metadata entries, i.e. android.lens.focusDistance,
+            android.lens.focusRange, android.lens.info.hyperfocalDistance, and
+            android.lens.info.minimumFocusDistance.
+            </details>
+          <tag id="V1" />
+        </entry>
         </namespace>
         <entry name="facing" type="byte" visibility="public" enum="true">
           <enum>
@@ -2253,7 +2295,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>The range of scene distances that are in
           sharp focus (depth of field)</description>
           <units>pair of focus distances in diopters: (near,
-          far)</units>
+          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>

diff --git a/camera/include/system/camera_metadata_tags.h b/camera/include/system/camera_metadata_tags.h
index 14b61d5..56eb671 100644 (file)
--- a/camera/include/system/camera_metadata_tags.h
+++ b/camera/include/system/camera_metadata_tags.h
@@ -224,6 +224,7 @@ typedef enum camera_metadata_tag {
     ANDROID_LENS_INFO_HYPERFOCAL_DISTANCE,            // float        | public
     ANDROID_LENS_INFO_MINIMUM_FOCUS_DISTANCE,         // float        | public
     ANDROID_LENS_INFO_SHADING_MAP_SIZE,               // int32[]      | public
+    ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION,     // enum         | public
     ANDROID_LENS_INFO_END,
 
     ANDROID_NOISE_REDUCTION_MODE =                    // enum         | public
@@ -600,6 +601,13 @@ typedef enum camera_metadata_enum_android_lens_state {
 } camera_metadata_enum_android_lens_state_t;
 
 
+// ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION
+typedef enum camera_metadata_enum_android_lens_info_focus_distance_calibration {
+    ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION_UNCALIBRATED,
+    ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION_APPROXIMATE,
+    ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION_CALIBRATED,
+} camera_metadata_enum_android_lens_info_focus_distance_calibration_t;
+
 
 // ANDROID_NOISE_REDUCTION_MODE
 typedef enum camera_metadata_enum_android_noise_reduction_mode {

diff --git a/camera/src/camera_metadata_tag_info.c b/camera/src/camera_metadata_tag_info.c
index 7e9d483..66f600a 100644 (file)
--- a/camera/src/camera_metadata_tag_info.c
+++ b/camera/src/camera_metadata_tag_info.c
@@ -327,6 +327,8 @@ static tag_info_t android_lens_info[ANDROID_LENS_INFO_END -
     { "minimumFocusDistance",          TYPE_FLOAT  },
     [ ANDROID_LENS_INFO_SHADING_MAP_SIZE - ANDROID_LENS_INFO_START ] =
     { "shadingMapSize",                TYPE_INT32  },
+    [ ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION - ANDROID_LENS_INFO_START ] =
+    { "focusDistanceCalibration",      TYPE_BYTE   },
 };
 
 static tag_info_t android_noise_reduction[ANDROID_NOISE_REDUCTION_END -
@@ -1441,6 +1443,25 @@ int camera_metadata_enum_snprint(uint32_t tag,
         case ANDROID_LENS_INFO_SHADING_MAP_SIZE: {
             break;
         }
+        case ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION: {
+            switch (value) {
+                case ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION_UNCALIBRATED:
+                    msg = "UNCALIBRATED";
+                    ret = 0;
+                    break;
+                case ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION_APPROXIMATE:
+                    msg = "APPROXIMATE";
+                    ret = 0;
+                    break;
+                case ANDROID_LENS_INFO_FOCUS_DISTANCE_CALIBRATION_CALIBRATED:
+                    msg = "CALIBRATED";
+                    ret = 0;
+                    break;
+                default:
+                    msg = "error: enum value out of range";
+            }
+            break;
+        }
 
         case ANDROID_NOISE_REDUCTION_MODE: {
             switch (value) {