Camera: update video stabilization API doc.

Update the video stabilization API description
to specify which scenarios guarantee stabilization
is performed if the control is set to ON and the
static metadata supports stabilization ON.

Bug: 23353979
Change-Id: I0f8662864e1c397c0a53edf11a685de2f6feb7f2

2 files changed, 31 insertions, 3 deletions

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 4825c6b0..18e074b1 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -4091,7 +4091,7 @@ active.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Video stabilization automatically translates and scales images from
+              <p>Video stabilization automatically warps images from
 the camera in order to stabilize motion between consecutive frames.<wbr/></p>
 <p>If enabled,<wbr/> video stabilization can modify the
 <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> to keep the video stream stabilized.<wbr/></p>
@@ -4101,6 +4101,15 @@ in capture result metadata.<wbr/> For example,<wbr/> When "ON" mode is requested
 the video stabilization modes in the first several capture results may
 still be "OFF",<wbr/> and it will become "ON" when the initialization is
 done.<wbr/></p>
+<p>In addition,<wbr/> not all recording sizes or frame rates may be supported for
+stabilization by a device that reports stabilization support.<wbr/> It is guaranteed
+that an output targeting a MediaRecorder or MediaCodec will be stabilized if
+the recording resolution is less than or equal to 1920 x 1080 (width less than
+or equal to 1920,<wbr/> height less than or equal to 1080),<wbr/> and the recording
+frame rate is less than or equal to 30fps.<wbr/>  At other sizes,<wbr/> the CaptureResult
+<a href="#controls_android.control.videoStabilizationMode">android.<wbr/>control.<wbr/>video<wbr/>Stabilization<wbr/>Mode</a> field will return
+OFF if the recording output is not stabilized,<wbr/> or if there are no output
+Surface types that can be stabilized.<wbr/></p>
 <p>If a camera device supports both this mode and OIS
 (<a href="#controls_android.lens.opticalStabilizationMode">android.<wbr/>lens.<wbr/>optical<wbr/>Stabilization<wbr/>Mode</a>),<wbr/> turning both modes on may
 produce undesirable interaction,<wbr/> so it is recommended not to enable
@@ -8561,7 +8570,7 @@ active.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Video stabilization automatically translates and scales images from
+              <p>Video stabilization automatically warps images from
 the camera in order to stabilize motion between consecutive frames.<wbr/></p>
 <p>If enabled,<wbr/> video stabilization can modify the
 <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> to keep the video stream stabilized.<wbr/></p>
@@ -8571,6 +8580,15 @@ in capture result metadata.<wbr/> For example,<wbr/> When "ON" mode is requested
 the video stabilization modes in the first several capture results may
 still be "OFF",<wbr/> and it will become "ON" when the initialization is
 done.<wbr/></p>
+<p>In addition,<wbr/> not all recording sizes or frame rates may be supported for
+stabilization by a device that reports stabilization support.<wbr/> It is guaranteed
+that an output targeting a MediaRecorder or MediaCodec will be stabilized if
+the recording resolution is less than or equal to 1920 x 1080 (width less than
+or equal to 1920,<wbr/> height less than or equal to 1080),<wbr/> and the recording
+frame rate is less than or equal to 30fps.<wbr/>  At other sizes,<wbr/> the CaptureResult
+<a href="#controls_android.control.videoStabilizationMode">android.<wbr/>control.<wbr/>video<wbr/>Stabilization<wbr/>Mode</a> field will return
+OFF if the recording output is not stabilized,<wbr/> or if there are no output
+Surface types that can be stabilized.<wbr/></p>
 <p>If a camera device supports both this mode and OIS
 (<a href="#controls_android.lens.opticalStabilizationMode">android.<wbr/>lens.<wbr/>optical<wbr/>Stabilization<wbr/>Mode</a>),<wbr/> turning both modes on may
 produce undesirable interaction,<wbr/> so it is recommended not to enable
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index 612fd4f4..aac0acfc 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -1789,7 +1789,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           <description>Whether video stabilization is
           active.</description>
           <details>
-          Video stabilization automatically translates and scales images from
+          Video stabilization automatically warps images from
           the camera in order to stabilize motion between consecutive frames.
 
           If enabled, video stabilization can modify the
@@ -1802,6 +1802,16 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           still be "OFF", and it will become "ON" when the initialization is
           done.
 
+          In addition, not all recording sizes or frame rates may be supported for
+          stabilization by a device that reports stabilization support. It is guaranteed
+          that an output targeting a MediaRecorder or MediaCodec will be stabilized if
+          the recording resolution is less than or equal to 1920 x 1080 (width less than
+          or equal to 1920, height less than or equal to 1080), and the recording
+          frame rate is less than or equal to 30fps.  At other sizes, the CaptureResult
+          android.control.videoStabilizationMode field will return
+          OFF if the recording output is not stabilized, or if there are no output
+          Surface types that can be stabilized.
+
           If a camera device supports both this mode and OIS
           (android.lens.opticalStabilizationMode), turning both modes on may
           produce undesirable interaction, so it is recommended not to enable