From 9c8fe185347e4c9c92d8c4a70d65d2957f5a9873 Mon Sep 17 00:00:00 2001
From: Jayant Chowdhary <jchowdhary@google.com>
Date: Tue, 19 May 2020 17:56:08 -0700
Subject: [PATCH] camera2: Add some more docs to getConcurrentCameraIds

- specifying the order of camera open and session configuration.
- explaining the use of CONTROL_ZOOM_RATIO with concurrent operation of cameras.

Bug: 151891611

Test: make doc-comment-check-docs

Change-Id: I3ee3f114f7295570aa6af5dbe35bb32db555811b
Signed-off-by: Jayant Chowdhary <jchowdhary@google.com>
---
 .../android/hardware/camera2/CameraManager.java   | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/core/java/android/hardware/camera2/CameraManager.java b/core/java/android/hardware/camera2/CameraManager.java
index 230aa044a9db5..cf133d2e75440 100644
--- a/core/java/android/hardware/camera2/CameraManager.java
+++ b/core/java/android/hardware/camera2/CameraManager.java
@@ -138,10 +138,25 @@ public final class CameraManager {
      * client camera application. Using these camera devices concurrently by two different
      * applications is not guaranteed to be supported, however.</p>
      *
+     * <p>For concurrent operation, in chronological order :
+     * - Applications must first close any open cameras that have sessions configured, using
+     *   {@link CameraDevice#close}.
+     * - All camera devices intended to be operated concurrently, must be opened using
+     *   {@link #openCamera}, before configuring sessions on any of the camera devices.</p>
+     *
      * <p>Each device in a combination, is guaranteed to support stream combinations which may be
      * obtained by querying {@link #getCameraCharacteristics} for the key
      * {@link android.hardware.camera2.CameraCharacteristics#SCALER_MANDATORY_CONCURRENT_STREAM_COMBINATIONS}.</p>
      *
+     * <p>For concurrent operation, if a camera device has a non null zoom ratio range as specified
+     * by
+     * {@link android.hardware.camera2.CameraCharacteristics#CONTROL_ZOOM_RATIO_RANGE},
+     * its complete zoom ratio range may not apply. Applications can use
+     * {@link android.hardware.camera2.CaptureRequest#CONTROL_ZOOM_RATIO} >=1 and  <=
+     * {@link android.hardware.camera2.CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM}
+     * during concurrent operation.
+     * <p>
+     *
      * <p>The set of combinations may include camera devices that may be in use by other camera API
      * clients.</p>
      *