From 161c29c09f9c24f21d75f7e809b664b7a4cd39a3 Mon Sep 17 00:00:00 2001
From: Jianing Wei <jianingwei@google.com>
Date: Tue, 29 Sep 2015 14:01:43 -0700
Subject: [PATCH] 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
---
 camera/docs/docs.html               | 22 ++++++++++++++++++++--
 camera/docs/metadata_properties.xml | 12 +++++++++++-
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 495ea6e6..94a3ce4e 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 dae74e1b..6f0d0083 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
-- 
2.11.0