From d216f25f6b0743e2ca5a4d138d8763fd60924358 Mon Sep 17 00:00:00 2001
From: Shuzhen Wang <shuzhenwang@google.com>
Date: Tue, 30 Aug 2022 13:29:01 -0700
Subject: Camera: Clarify doc for onPhysicalCameraUnavailable

Clarify that no physical camera availability callbacks will be called
if the parent logical camera becomes unavailable.

Test: Build doc
Bug: 243738805
Change-Id: I339b7cedf1df10f89aa6ead0c67ed9f2bda9ed0c
---
 .../android/hardware/camera2/CameraManager.java    | 37 +++++++++++++++++++---
 1 file changed, 32 insertions(+), 5 deletions(-)

diff --git a/core/java/android/hardware/camera2/CameraManager.java b/core/java/android/hardware/camera2/CameraManager.java
index d6d3a97687b5..dff2f7ed1cf3 100644
--- a/core/java/android/hardware/camera2/CameraManager.java
+++ b/core/java/android/hardware/camera2/CameraManager.java
@@ -1204,6 +1204,20 @@ public final class CameraManager {
          * to begin with, {@link #onPhysicalCameraUnavailable} may be invoked after
          * {@link #onCameraAvailable}.</p>
          *
+         * <p>Limitation: Opening a logical camera disables the {@link #onPhysicalCameraAvailable}
+         * and {@link #onPhysicalCameraUnavailable} callbacks for its physical cameras. For example,
+         * if app A opens the camera device:</p>
+         *
+         * <ul>
+         *
+         * <li>All apps subscribing to ActivityCallback get {@link #onCameraUnavailable}.</li>
+         *
+         * <li>No app (including app A) subscribing to ActivityCallback gets
+         * {@link #onPhysicalCameraAvailable} or {@link #onPhysicalCameraUnavailable}, because
+         * the logical camera is unavailable (some app is using it).</li>
+         *
+         * </ul>
+         *
          * <p>The default implementation of this method does nothing.</p>
          *
          * @param cameraId The unique identifier of the logical multi-camera.
@@ -1221,11 +1235,24 @@ public final class CameraManager {
          * A previously-available physical camera has become unavailable for use.
          *
          * <p>By default, all of the physical cameras of a logical multi-camera are
-         * available, so {@link #onPhysicalCameraAvailable} is not called for any of the physical
-         * cameras of a logical multi-camera, when {@link #onCameraAvailable} for the logical
-         * multi-camera is invoked. If some specific physical cameras are unavailable
-         * to begin with, {@link #onPhysicalCameraUnavailable} may be invoked after
-         * {@link #onCameraAvailable}.</p>
+         * unavailable if the logical camera itself is unavailable.
+         * No availability callbacks will be called for any of the physical
+         * cameras of its parent logical multi-camera, when {@link #onCameraUnavailable} for
+         * the logical multi-camera is invoked.</p>
+         *
+         * <p>Limitation: Opening a logical camera disables the {@link #onPhysicalCameraAvailable}
+         * and {@link #onPhysicalCameraUnavailable} callbacks for its physical cameras. For example,
+         * if app A opens the camera device:</p>
+         *
+         * <ul>
+         *
+         * <li>All apps subscribing to ActivityCallback get {@link #onCameraUnavailable}.</li>
+         *
+         * <li>No app (including app A) subscribing to ActivityCallback gets
+         * {@link #onPhysicalCameraAvailable} or {@link #onPhysicalCameraUnavailable}, because
+         * the logical camera is unavailable (some app is using it).</li>
+         *
+         * </ul>
          *
          * <p>The default implementation of this method does nothing.</p>
          *
-- 
cgit v1.2.3-59-g8ed1b