From cad6619726fc322e9f0a2c958cd5e5cac319a795 Mon Sep 17 00:00:00 2001
From: Zhijun He <zhijunhe@google.com>
Date: Fri, 6 Feb 2015 13:42:40 -0800
Subject: [PATCH] camera-metadata: clarify the AE precapture trigger API spec

Doc only change.

Bug: 19301706
Change-Id: I8f94ee5ace6dd3040ee2f350d589e24e53694f1b
---
 camera/docs/docs.html               | 24 ++++++++++++++++++++----
 camera/docs/metadata_properties.xml | 13 +++++++++++--
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 32c42a3b..0674494e 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -2491,9 +2491,9 @@ metering sequence when it processes this request.<wbr/></p>
             <td class="entry_details" colspan="5">
               <p>This entry is normally set to IDLE,<wbr/> or is not
 included at all in the request settings.<wbr/> When included and
-set to START,<wbr/> the camera device will trigger the autoexposure
+set to START,<wbr/> the camera device will trigger the auto-exposure (AE)
 precapture metering sequence.<wbr/></p>
-<p>The precapture sequence should triggered before starting a
+<p>The precapture sequence should be triggered before starting a
 high-quality still capture for final metering decisions to
 be made,<wbr/> and for firing pre-capture flash pulses to estimate
 scene brightness and required final capture flash power,<wbr/> when
@@ -2501,6 +2501,14 @@ the flash is enabled.<wbr/></p>
 <p>Normally,<wbr/> this entry should be set to START for only a
 single request,<wbr/> and the application should wait until the
 sequence completes before starting a new one.<wbr/></p>
+<p>When a precapture metering sequence is finished,<wbr/> the camera device
+may lock the auto-exposure routine internally to be able to accurately expose the
+subsequent still capture image (<code><a href="#controls_android.control.captureIntent">android.<wbr/>control.<wbr/>capture<wbr/>Intent</a> == STILL_<wbr/>CAPTURE</code>).<wbr/>
+For this case,<wbr/> the AE may not resume normal scan if no subsequent still capture is
+submitted.<wbr/> To ensure that the AE routine restarts normal scan,<wbr/> the application should
+submit a request with <code><a href="#controls_android.control.aeLock">android.<wbr/>control.<wbr/>ae<wbr/>Lock</a> == true</code>,<wbr/> followed by a request
+with <code><a href="#controls_android.control.aeLock">android.<wbr/>control.<wbr/>ae<wbr/>Lock</a> == false</code>,<wbr/> if the application decides not to submit a
+still capture request after the precapture sequence completes.<wbr/></p>
 <p>The exact effect of auto-exposure (AE) precapture trigger
 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
@@ -5617,9 +5625,9 @@ metering sequence when it processes this request.<wbr/></p>
             <td class="entry_details" colspan="5">
               <p>This entry is normally set to IDLE,<wbr/> or is not
 included at all in the request settings.<wbr/> When included and
-set to START,<wbr/> the camera device will trigger the autoexposure
+set to START,<wbr/> the camera device will trigger the auto-exposure (AE)
 precapture metering sequence.<wbr/></p>
-<p>The precapture sequence should triggered before starting a
+<p>The precapture sequence should be triggered before starting a
 high-quality still capture for final metering decisions to
 be made,<wbr/> and for firing pre-capture flash pulses to estimate
 scene brightness and required final capture flash power,<wbr/> when
@@ -5627,6 +5635,14 @@ the flash is enabled.<wbr/></p>
 <p>Normally,<wbr/> this entry should be set to START for only a
 single request,<wbr/> and the application should wait until the
 sequence completes before starting a new one.<wbr/></p>
+<p>When a precapture metering sequence is finished,<wbr/> the camera device
+may lock the auto-exposure routine internally to be able to accurately expose the
+subsequent still capture image (<code><a href="#controls_android.control.captureIntent">android.<wbr/>control.<wbr/>capture<wbr/>Intent</a> == STILL_<wbr/>CAPTURE</code>).<wbr/>
+For this case,<wbr/> the AE may not resume normal scan if no subsequent still capture is
+submitted.<wbr/> To ensure that the AE routine restarts normal scan,<wbr/> the application should
+submit a request with <code><a href="#controls_android.control.aeLock">android.<wbr/>control.<wbr/>ae<wbr/>Lock</a> == true</code>,<wbr/> followed by a request
+with <code><a href="#controls_android.control.aeLock">android.<wbr/>control.<wbr/>ae<wbr/>Lock</a> == false</code>,<wbr/> if the application decides not to submit a
+still capture request after the precapture sequence completes.<wbr/></p>
 <p>The exact effect of auto-exposure (AE) precapture trigger
 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
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index 4eb2d1ea..d7ce6df6 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -705,10 +705,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           metering sequence when it processes this request.</description>
           <details>This entry is normally set to IDLE, or is not
           included at all in the request settings. When included and
-          set to START, the camera device will trigger the autoexposure
+          set to START, the camera device will trigger the auto-exposure (AE)
           precapture metering sequence.
 
-          The precapture sequence should triggered before starting a
+          The precapture sequence should be triggered before starting a
           high-quality still capture for final metering decisions to
           be made, and for firing pre-capture flash pulses to estimate
           scene brightness and required final capture flash power, when
@@ -718,6 +718,15 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           single request, and the application should wait until the
           sequence completes before starting a new one.
 
+          When a precapture metering sequence is finished, the camera device
+          may lock the auto-exposure routine internally to be able to accurately expose the
+          subsequent still capture image (`android.control.captureIntent == STILL_CAPTURE`).
+          For this case, the AE may not resume normal scan if no subsequent still capture is
+          submitted. To ensure that the AE routine restarts normal scan, the application should
+          submit a request with `android.control.aeLock == true`, followed by a request
+          with `android.control.aeLock == false`, if the application decides not to submit a
+          still capture request after the precapture sequence completes.
+
           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
-- 
2.11.0