camera3: Update sceneModeOverrides tag spec.

Change-Id: Ia16d283df2ffc1b21cb68a6f73280629dd259306

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index b05afe9..3d652bf 100644 (file)
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -3023,7 +3023,7 @@ regions can be listed for metering?</p>
         
                 
           <tr class="entry" id="static_android.control.sceneModeOverrides">
-            <td class="entry_name" rowspan="3">
+            <td class="entry_name" rowspan="5">
               android.<wbr/>control.<wbr/>scene<wbr/>Mode<wbr/>Overrides
             </td>
             <td class="entry_type">
@@ -3039,19 +3039,19 @@ regions can be listed for metering?</p>
             </td> <!-- entry_type -->
 
             <td class="entry_description">
-              <p>List of AE,<wbr/> AWB,<wbr/> and AF modes to use for
-each available scene mode</p>
+              <p>Ordered list of auto-exposure,<wbr/> auto-white balance,<wbr/> and auto-focus
+settings to use with each available scene mode.<wbr/></p>
             </td>
 
             <td class="entry_units">
             </td>
 
             <td class="entry_range">
-              <p>For each listed scene mode,<wbr/> lists the aeMode,<wbr/>
-awbMode,<wbr/> and afMode that the HAL wants to use for that
-scene mode.<wbr/></p>
-<p>For each entry,<wbr/> the order is {aeMode,<wbr/> awbMode,<wbr/> afMode} in
-order of increasing index</p>
+              <p>For each available scene mode,<wbr/> the list must contain three
+entries containing the <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> values used
+by the camera device.<wbr/> The entry order is <code>(aeMode,<wbr/> awbMode,<wbr/> afMode)</code>
+where aeMode has the lowest index position.<wbr/></p>
             </td>
 
             <td class="entry_tags">
@@ -3066,26 +3066,38 @@ order of increasing index</p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>When a scene mode is enabled,<wbr/> the HAL is expected
-to override aeMode,<wbr/> awbMode,<wbr/> and afMode with its
-preferred settings for that scene mode.<wbr/></p>
-<p>To simplify communication with old camera API applications,<wbr/>
-the service wants this override list in the static metadata.<wbr/>
-The order of this list matches that of availableSceneModes,<wbr/>
-with 3 entires for each scene mode.<wbr/>  The overrides listed
-for SCENE_<wbr/>MODE_<wbr/>FACE_<wbr/>PRIORITY are ignored,<wbr/> since for that
-mode,<wbr/> the application-set aeMode,<wbr/> awbMode,<wbr/> and afMode are
-used instead,<wbr/> like they are when <a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> is
-AUTO.<wbr/></p>
-<p>It is recommended that for FACE_<wbr/>PRIORITY,<wbr/> the overrides
-should be set to 0.<wbr/> As an example,<wbr/> if availableSceneModes is
-{ FACE_<wbr/>PRIORITY,<wbr/> ACTION,<wbr/> NIGHT },<wbr/> then the service expects
-this field to have 9 entries; for example { 0 ,<wbr/> 0,<wbr/> 0,<wbr/>
-ON_<wbr/>AUTO_<wbr/>FLASH,<wbr/> AUTO,<wbr/> CONTINUOUS_<wbr/>PICTURE,<wbr/> ON_<wbr/>AUTO_<wbr/>FLASH,<wbr/>
-INCANDESCENT,<wbr/> AUTO }</p>
+              <p>When a scene mode is enabled,<wbr/> the camera device is expected
+to override <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> with its preferred settings for
+that scene mode.<wbr/></p>
+<p>The order of this list matches that of availableSceneModes,<wbr/>
+with 3 entries for each mode.<wbr/>  The overrides listed
+for FACE_<wbr/>PRIORITY are ignored,<wbr/> since for that
+mode the application-set <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> values are
+used instead,<wbr/> matching the behavior when android.<wbr/>control.<wbr/>mode
+is set to AUTO.<wbr/> It is recommended that the FACE_<wbr/>PRIORITY
+overrides should be set to 0.<wbr/></p>
+<p>For example,<wbr/> if availableSceneModes contains
+<code>(FACE_<wbr/>PRIORITY,<wbr/> ACTION,<wbr/> NIGHT)</code>,<wbr/>  then the camera framework
+expects sceneModeOverrides to have 9 entries formatted like:
+<code>(0,<wbr/> 0,<wbr/> 0,<wbr/> ON_<wbr/>AUTO_<wbr/>FLASH,<wbr/> AUTO,<wbr/> CONTINUOUS_<wbr/>PICTURE,<wbr/>
+ON_<wbr/>AUTO_<wbr/>FLASH,<wbr/> INCANDESCENT,<wbr/> AUTO)</code>.<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>To maintain backward compatibility,<wbr/> this list will be made available
+in the static metadata of the camera service.<wbr/>  The camera service will
+use these values to set <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> when using a scene
+mode other than FACE_<wbr/>PRIORITY.<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 db40996..df0b8b8 100644 (file)
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -1047,33 +1047,45 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>3</size>
             <size>length(availableSceneModes)</size>
           </array>
-          <description>List of AE, AWB, and AF modes to use for
-          each available scene mode</description>
-          <range>For each listed scene mode, lists the aeMode,
-          awbMode, and afMode that the HAL wants to use for that
-          scene mode.
-
-          For each entry, the order is {aeMode, awbMode, afMode} in
-          order of increasing index</range>
-          <details>When a scene mode is enabled, the HAL is expected
-          to override aeMode, awbMode, and afMode with its
-          preferred settings for that scene mode.
-
-          To simplify communication with old camera API applications,
-          the service wants this override list in the static metadata.
+          <description>
+          Ordered list of auto-exposure, auto-white balance, and auto-focus
+          settings to use with each available scene mode.
+          </description>
+          <range>
+          For each available scene mode, the list must contain three
+          entries containing the android.control.aeMode,
+          android.control.awbMode, and android.control.afMode values used
+          by the camera device. The entry order is `(aeMode, awbMode, afMode)`
+          where aeMode has the lowest index position.
+          </range>
+          <details>
+          When a scene mode is enabled, the camera device is expected
+          to override android.control.aeMode, android.control.awbMode,
+          and android.control.afMode with its preferred settings for
+          that scene mode.
+
           The order of this list matches that of availableSceneModes,
-          with 3 entires for each scene mode.  The overrides listed
-          for SCENE_MODE_FACE_PRIORITY are ignored, since for that
-          mode, the application-set aeMode, awbMode, and afMode are
-          used instead, like they are when android.control.mode is
-          AUTO.
-
-          It is recommended that for FACE_PRIORITY, the overrides
-          should be set to 0. As an example, if availableSceneModes is
-          { FACE_PRIORITY, ACTION, NIGHT }, then the service expects
-          this field to have 9 entries; for example { 0 , 0, 0,
-          ON_AUTO_FLASH, AUTO, CONTINUOUS_PICTURE, ON_AUTO_FLASH,
-          INCANDESCENT, AUTO }</details>
+          with 3 entries for each mode.  The overrides listed
+          for FACE_PRIORITY are ignored, since for that
+          mode the application-set android.control.aeMode,
+          android.control.awbMode, and android.control.afMode values are
+          used instead, matching the behavior when android.control.mode
+          is set to AUTO. It is recommended that the FACE_PRIORITY
+          overrides should be set to 0.
+
+          For example, if availableSceneModes contains
+          `(FACE_PRIORITY, ACTION, NIGHT)`,  then the camera framework
+          expects sceneModeOverrides to have 9 entries formatted like:
+          `(0, 0, 0, ON_AUTO_FLASH, AUTO, CONTINUOUS_PICTURE,
+          ON_AUTO_FLASH, INCANDESCENT, AUTO)`.
+          </details>
+          <hal_details>
+          To maintain backward compatibility, this list will be made available
+          in the static metadata of the camera service.  The camera service will
+          use these values to set android.control.aeMode,
+          android.control.awbMode, and android.control.afMode when using a scene
+          mode other than FACE_PRIORITY.
+          </hal_details>
           <tag id="BC" />
         </entry>
       </static>