camera_metadata: Doc update for lens locking behavior

Need clarify what the HAL should when focus is locked.

Change-Id: Ia0d58f534210a5f94ae3e3773f9ea88b4c646578

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index b9cfb6a..286a82f 100644 (file)
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -2164,7 +2164,7 @@ state transition details.<wbr/></p>
                 
           <tr class="entry" id="controls_android.control.afMode">
             <td class="entry_name
-             " rowspan="3">
+             " rowspan="5">
               android.<wbr/>control.<wbr/>af<wbr/>Mode
             </td>
             <td class="entry_type">
@@ -2284,6 +2284,33 @@ in result metadata.<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>When afMode is AUTO or MACRO,<wbr/> the lens must not move until an AF trigger is sent in a
+request (<a href="#controls_android.control.afTrigger">android.<wbr/>control.<wbr/>af<wbr/>Trigger</a> <code>==</code> START).<wbr/> After an AF trigger,<wbr/> the afState will end
+up with either FOCUSED_<wbr/>LOCKED or NOT_<wbr/>FOCUSED_<wbr/>LOCKED state (see
+<a href="#dynamic_android.control.afState">android.<wbr/>control.<wbr/>af<wbr/>State</a> for detailed state transitions),<wbr/> which indicates that the lens is
+locked and will not move.<wbr/> If camera movement (e.<wbr/>g.<wbr/> tilting camera) causes the lens to move
+after the lens is locked,<wbr/> the HAL must compensate this movement appropriately such that
+the same focal plane remains in focus.<wbr/></p>
+<p>When afMode is one of the continuous auto focus modes,<wbr/> the HAL is free to start a AF
+scan whenever it's not locked.<wbr/> When the lens is locked after an AF trigger
+(see <a href="#dynamic_android.control.afState">android.<wbr/>control.<wbr/>af<wbr/>State</a> for detailed state transitions),<wbr/> the HAL should maintain the
+same lock behavior as above.<wbr/></p>
+<p>When afMode is OFF,<wbr/> the application controls focus manually.<wbr/> The accuracy of the
+focus distance control depends on the <a href="#static_android.lens.info.focusDistanceCalibration">android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration</a>.<wbr/>
+However,<wbr/> the lens must not move regardless of the camera movement for any focus distance
+manual control.<wbr/></p>
+<p>To put this in concrete terms,<wbr/> if the camera has lens elements which may move based on
+camera orientation or motion (e.<wbr/>g.<wbr/> due to gravity),<wbr/> then the HAL must drive the lens to
+remain in a fixed position invariant to the camera's orientation or motion,<wbr/> for example,<wbr/>
+by using accelerometer measurements in the lens control logic.<wbr/> This is a typical issue
+that will arise on camera modules with open-loop VCMs.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
            <!-- end of entry -->
@@ -4981,7 +5008,7 @@ transient states between two results.<wbr/> See below table for examples:</p>
                 
           <tr class="entry" id="dynamic_android.control.afMode">
             <td class="entry_name
-             " rowspan="3">
+             " rowspan="5">
               android.<wbr/>control.<wbr/>af<wbr/>Mode
             </td>
             <td class="entry_type">
@@ -5101,6 +5128,33 @@ in result metadata.<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>When afMode is AUTO or MACRO,<wbr/> the lens must not move until an AF trigger is sent in a
+request (<a href="#controls_android.control.afTrigger">android.<wbr/>control.<wbr/>af<wbr/>Trigger</a> <code>==</code> START).<wbr/> After an AF trigger,<wbr/> the afState will end
+up with either FOCUSED_<wbr/>LOCKED or NOT_<wbr/>FOCUSED_<wbr/>LOCKED state (see
+<a href="#dynamic_android.control.afState">android.<wbr/>control.<wbr/>af<wbr/>State</a> for detailed state transitions),<wbr/> which indicates that the lens is
+locked and will not move.<wbr/> If camera movement (e.<wbr/>g.<wbr/> tilting camera) causes the lens to move
+after the lens is locked,<wbr/> the HAL must compensate this movement appropriately such that
+the same focal plane remains in focus.<wbr/></p>
+<p>When afMode is one of the continuous auto focus modes,<wbr/> the HAL is free to start a AF
+scan whenever it's not locked.<wbr/> When the lens is locked after an AF trigger
+(see <a href="#dynamic_android.control.afState">android.<wbr/>control.<wbr/>af<wbr/>State</a> for detailed state transitions),<wbr/> the HAL should maintain the
+same lock behavior as above.<wbr/></p>
+<p>When afMode is OFF,<wbr/> the application controls focus manually.<wbr/> The accuracy of the
+focus distance control depends on the <a href="#static_android.lens.info.focusDistanceCalibration">android.<wbr/>lens.<wbr/>info.<wbr/>focus<wbr/>Distance<wbr/>Calibration</a>.<wbr/>
+However,<wbr/> the lens must not move regardless of the camera movement for any focus distance
+manual control.<wbr/></p>
+<p>To put this in concrete terms,<wbr/> if the camera has lens elements which may move based on
+camera orientation or motion (e.<wbr/>g.<wbr/> due to gravity),<wbr/> then the HAL must drive the lens to
+remain in a fixed position invariant to the camera's orientation or motion,<wbr/> for example,<wbr/>
+by using accelerometer measurements in the lens control logic.<wbr/> This is a typical issue
+that will arise on camera modules with open-loop VCMs.<wbr/></p>
+            </td>
+          </tr>
 
           <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
            <!-- end of entry -->

diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index a05166a..865613d 100644 (file)
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -637,6 +637,31 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           If the lens is controlled by the camera device auto-focus algorithm,
           the camera device will report the current AF status in android.control.afState
           in result metadata.</details>
+          <hal_details>
+          When afMode is AUTO or MACRO, the lens must not move until an AF trigger is sent in a
+          request (android.control.afTrigger `==` START). After an AF trigger, the afState will end
+          up with either FOCUSED_LOCKED or NOT_FOCUSED_LOCKED state (see
+          android.control.afState for detailed state transitions), which indicates that the lens is
+          locked and will not move. If camera movement (e.g. tilting camera) causes the lens to move
+          after the lens is locked, the HAL must compensate this movement appropriately such that
+          the same focal plane remains in focus.
+
+          When afMode is one of the continuous auto focus modes, the HAL is free to start a AF
+          scan whenever it's not locked. When the lens is locked after an AF trigger
+          (see android.control.afState for detailed state transitions), the HAL should maintain the
+          same lock behavior as above.
+
+          When afMode is OFF, the application controls focus manually. The accuracy of the
+          focus distance control depends on the android.lens.info.focusDistanceCalibration.
+          However, the lens must not move regardless of the camera movement for any focus distance
+          manual control.
+
+          To put this in concrete terms, if the camera has lens elements which may move based on
+          camera orientation or motion (e.g. due to gravity), then the HAL must drive the lens to
+          remain in a fixed position invariant to the camera's orientation or motion, for example,
+          by using accelerometer measurements in the lens control logic. This is a typical issue
+          that will arise on camera modules with open-loop VCMs.
+          </hal_details>
           <tag id="BC" />
         </entry>
         <entry name="afRegions" type="int32" visibility="public"