From 2260bc072c89fc9d9542679db4c5f32f81b4e6f3 Mon Sep 17 00:00:00 2001
From: Austin Borger <borgera@google.com>
Date: Thu, 30 Mar 2023 13:14:38 -0700
Subject: [PATCH] Camera: Modify CameraCharacteristics documentation about
 static keys.

Beginning in Android TM, we have relaxed the requirement that
characteristics keys be static. SENSOR_ORIENTATION may change based on
the state of the device. Re-word the parts of the documentation making
a guarantee that key values don't change.

Bug: 271845957
Test: m sdk
Change-Id: Ib0e2e6113afdc01ac6c29822a6ab12c19c3fd9f0
---
 .../hardware/camera2/CameraCharacteristics.java        | 10 +++++-----
 core/java/android/hardware/camera2/CameraMetadata.java |  7 ++++---
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java
index 0e4c3c0f12a17..e908ced06acd5 100644
--- a/core/java/android/hardware/camera2/CameraCharacteristics.java
+++ b/core/java/android/hardware/camera2/CameraCharacteristics.java
@@ -41,9 +41,12 @@ import java.util.Set;
  * <p>The properties describing a
  * {@link CameraDevice CameraDevice}.</p>
  *
- * <p>These properties are fixed for a given CameraDevice, and can be queried
+ * <p>These properties are primarily fixed for a given CameraDevice, and can be queried
  * through the {@link CameraManager CameraManager}
- * interface with {@link CameraManager#getCameraCharacteristics}.</p>
+ * interface with {@link CameraManager#getCameraCharacteristics}. Beginning with API level 32, some
+ * properties such as {@link #SENSOR_ORIENTATION} may change dynamically based on the state of the
+ * device. For information on whether a specific value is fixed, see the documentation for its key.
+ * </p>
  *
  * <p>When obtained by a client that does not hold the CAMERA permission, some metadata values are
  * not included. The list of keys that require the permission is given by
@@ -281,9 +284,6 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
      * <p>The field definitions can be
      * found in {@link CameraCharacteristics}.</p>
      *
-     * <p>Querying the value for the same key more than once will return a value
-     * which is equal to the previous queried value.</p>
-     *
      * @throws IllegalArgumentException if the key was not valid
      *
      * @param key The characteristics field to read.
diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java
index a7e28e2f40d15..4950373449e21 100644
--- a/core/java/android/hardware/camera2/CameraMetadata.java
+++ b/core/java/android/hardware/camera2/CameraMetadata.java
@@ -41,9 +41,10 @@ import java.util.List;
  * </p>
  *
  * <p>
- * All instances of CameraMetadata are immutable. The list of keys with {@link #getKeys()}
- * never changes, nor do the values returned by any key with {@code #get} throughout
- * the lifetime of the object.
+ * All instances of CameraMetadata are immutable. Beginning with API level 32, the list of keys
+ * returned by {@link #getKeys()} may change depending on the state of the device, as may the
+ * values returned by any key with {@code #get} throughout the lifetime of the object. For
+ * information on whether a specific value is fixed, see the documentation for its key.
  * </p>
  *
  * @see CameraDevice