From 585305da3215cb9498449170e407ff14f79484ce Mon Sep 17 00:00:00 2001
From: Eino-Ville Talvala <etalvala@google.com>
Date: Mon, 23 Mar 2020 12:41:17 -0700
Subject: [PATCH] Camera: Improve docs for getOutputMinFrameDuration

The current text was misleading, since minimum frame duration of a
stream affects the aggregate minimum frame duration of a session
whether a stream is in use for a given request stream or not.

Test: Docs build
Bug: 147080626
Change-Id: Ic884cd0bb3ea184383944cb78e9713d6044b1959
---
 .../params/StreamConfigurationMap.java        | 30 +++++++++----------
 1 file changed, 14 insertions(+), 16 deletions(-)

diff --git a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java
index 478922df51865..c37f9fe2465cf 100644
--- a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java
+++ b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java
@@ -865,22 +865,21 @@ public final class StreamConfigurationMap {
      * <p>{@code size} should be one of the ones returned by
      * {@link #getOutputSizes(int)}.</p>
      *
-     * <p>This should correspond to the frame duration when only that stream is active, with all
-     * processing (typically in {@code android.*.mode}) set to either {@code OFF} or {@code FAST}.
-     * </p>
+     * <p>This corresponds to the minimum frame duration (maximum frame rate) possible when only
+     * that stream is configured in a session, with all processing (typically in
+     * {@code android.*.mode}) set to either {@code OFF} or {@code FAST}.  </p>
      *
-     * <p>When multiple streams are used in a request, the minimum frame duration will be
-     * {@code max(individual stream min durations)}.</p>
+     * <p>When multiple streams are used in a session, the minimum frame duration will be
+     * {@code max(individual stream min durations)}.  See {@link #getOutputStallDuration} for
+     * details of timing for formats that may cause frame rate slowdown when they are targeted by a
+     * capture request.</p>
      *
      * <p>For devices that do not support manual sensor control
      * ({@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR}),
      * this function may return 0.</p>
      *
-     * <!--
-     * TODO: uncomment after adding input stream support
      * <p>The minimum frame duration of a stream (of a particular format, size) is the same
      * regardless of whether the stream is input or output.</p>
-     * -->
      *
      * @param format an image format from {@link ImageFormat} or {@link PixelFormat}
      * @param size an output-compatible size
@@ -918,22 +917,21 @@ public final class StreamConfigurationMap {
      * <p>{@code size} should be one of the ones returned by
      * {@link #getOutputSizes(int)}.</p>
      *
-     * <p>This should correspond to the frame duration when only that stream is active, with all
-     * processing (typically in {@code android.*.mode}) set to either {@code OFF} or {@code FAST}.
-     * </p>
+     * <p>This corresponds to the minimum frame duration (maximum frame rate) possible when only
+     * that stream is configured in a session, with all processing (typically in
+     * {@code android.*.mode}) set to either {@code OFF} or {@code FAST}.  </p>
      *
-     * <p>When multiple streams are used in a request, the minimum frame duration will be
-     * {@code max(individual stream min durations)}.</p>
+     * <p>When multiple streams are used in a session, the minimum frame duration will be
+     * {@code max(individual stream min durations)}.  See {@link #getOutputStallDuration} for
+     * details of timing for formats that may cause frame rate slowdown when they are targeted by a
+     * capture request.</p>
      *
      * <p>For devices that do not support manual sensor control
      * ({@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR}),
      * this function may return 0.</p>
      *
-     * <!--
-     * TODO: uncomment after adding input stream support
      * <p>The minimum frame duration of a stream (of a particular format, size) is the same
      * regardless of whether the stream is input or output.</p>
-     * -->
      *
      * @param klass
      *          a class which is supported by {@link #isOutputSupportedFor(Class)} and has a