Merge "Document setTargetRotation for ImageAnalysis" into androidx-master-dev

diff --git a/camera/camera-core/src/main/java/androidx/camera/core/ImageAnalysis.java b/camera/camera-core/src/main/java/androidx/camera/core/ImageAnalysis.java
index 0f60030d..da700a7 100644
--- a/camera/camera-core/src/main/java/androidx/camera/core/ImageAnalysis.java
+++ b/camera/camera-core/src/main/java/androidx/camera/core/ImageAnalysis.java

@@ -194,19 +194,26 @@
      * Sets the target rotation.
      *
      * <p>This informs the use case so it can adjust the rotation value sent to
-     * {@link Analyzer#analyze(ImageProxy, int)}.
-     *
-     * <p>In most cases this should be set to the current rotation returned by {@link
-     * Display#getRotation()}.  In that case, the rotation parameter sent to the analyzer will be
-     * the rotation, which if applied to the output image, will make the image match the display
-     * orientation.
+     * {@link Analyzer#analyze(ImageProxy, int)} which provides rotation information to the
+     * analysis method. The rotation parameter sent to the analyzer will be the rotation, which if
+     * applied to the output image, will make the image match target rotation specified here.
      *
      * <p>While rotation can also be set via
      * {@link ImageAnalysisConfig.Builder#setTargetRotation(int)}, using
      * {@link ImageAnalysis#setTargetRotation(int)} allows the target rotation to be set
-     * dynamically. This can be useful if an app locks itself to portrait, and uses the orientation
-     * sensor to set rotation, to process landscape images when the device is rotated by examining
-     * the rotation received by the Analyzer function.
+     * dynamically.
+     *
+     * <p>In general, it is best to use an {@link android.view.OrientationEventListener} to
+     * set the target rotation.  This way, the rotation output to the Analyzer will indicate
+     * which way is down for a given image.  This is important since display orientation may be
+     * locked by device default, user setting, or app configuration,
+     * and some devices may not transition to a reverse-portrait display orientation.  In
+     * these cases, use {@link androidx.camera.core.ImageAnalysis#setTargetRotation} to set
+     * target rotation dynamically according to the
+     * {@link android.view.OrientationEventListener}, without re-creating the use case.  Note
+     * the OrientationEventListener output of degrees in the range [0..359] should be converted to
+     * a surface rotation, i.e. one of {@link Surface#ROTATION_0}, {@link Surface#ROTATION_90},
+     * {@link Surface#ROTATION_180}, or {@link Surface#ROTATION_270}.
      *
      * <p>If not set here or by configuration, the target rotation will default to the value of
      * {@link Display#getRotation()} of the default display at the time the

diff --git a/camera/camera-core/src/main/java/androidx/camera/core/ImageAnalysisConfig.java b/camera/camera-core/src/main/java/androidx/camera/core/ImageAnalysisConfig.java
index e7ee347..55d6114 100644
--- a/camera/camera-core/src/main/java/androidx/camera/core/ImageAnalysisConfig.java
+++ b/camera/camera-core/src/main/java/androidx/camera/core/ImageAnalysisConfig.java

@@ -20,7 +20,6 @@
 import android.util.Pair;
 import android.util.Rational;
 import android.util.Size;
-import android.view.Display;
 import android.view.Surface;
 
 import androidx.annotation.NonNull;
@@ -849,12 +848,24 @@
         /**
          * Sets the rotation of the intended target for images from this configuration.
          *
+         * <p>The rotation parameter sent to the analyzer will be the rotation, which if applied to
+         * the output image, will make the image match target rotation specified here.
+         *
          * <p>This is one of four valid values: {@link Surface#ROTATION_0}, {@link
          * Surface#ROTATION_90}, {@link Surface#ROTATION_180}, {@link Surface#ROTATION_270}.
          * Rotation values are relative to the "natural" rotation, {@link Surface#ROTATION_0}.
          *
+         * <p>In general, it is best to additionally set the target rotation dynamically on the use
+         * case.  See
+         * {@link androidx.camera.core.ImageAnalysis#setTargetRotation(int)} for additional
+         * documentation.
+         *
          * <p>If not set, the target rotation will default to the value of
-         * {@link Display#getRotation()} of the default display at the time the use case is created.
+         * {@link android.view.Display#getRotation()} of the default display at the time the
+         * use case is created.
+         *
+         * @see androidx.camera.core.ImageAnalysis#setTargetRotation(int)
+         * @see android.view.OrientationEventListener
          *
          * @param rotation The rotation of the intended target.
          * @return The current Builder.