Merge "Add some API docs for common confusions" into main
diff --git a/core/java/android/content/pm/ActivityInfo.java b/core/java/android/content/pm/ActivityInfo.java
index 4f06209..0113129 100644
--- a/core/java/android/content/pm/ActivityInfo.java
+++ b/core/java/android/content/pm/ActivityInfo.java
@@ -451,6 +451,13 @@
* Value of {@link #colorMode} indicating that the activity should use a
* high dynamic range if the presentation display supports it.
*
+ * <p>Note: This does not impact SurfaceViews or SurfaceControls, as those have their own
+ * independent HDR support.</p>
+ *
+ * <p><b>Important:</b> Although this value was added in API 26, it is strongly recommended
+ * to avoid using it until API 34 which is when HDR support for the UI toolkit was officially
+ * added.</p>
+ *
* @see android.R.attr#colorMode
*/
public static final int COLOR_MODE_HDR = 2;
diff --git a/core/java/android/view/SurfaceView.java b/core/java/android/view/SurfaceView.java
index 1d70d18..455e680 100644
--- a/core/java/android/view/SurfaceView.java
+++ b/core/java/android/view/SurfaceView.java
@@ -830,7 +830,8 @@
/**
* Sets the desired amount of HDR headroom to be used when HDR content is presented on this
- * SurfaceView.
+ * SurfaceView. This is expressed as the ratio of maximum HDR white point over the SDR
+ * white point, not as absolute nits.
*
* <p>By default the system will choose an amount of HDR headroom that is appropriate
* for the underlying device capabilities & bit-depth of the panel. However, for some types
@@ -844,6 +845,10 @@
* See {@link Display#getHdrSdrRatio()} for more information as well as how to query the
* current value.</p>
*
+ * <p>Note: This API operates independently of both the
+ * {@link Window#setColorMode Widow color mode} and the
+ * {@link Window#setDesiredHdrHeadroom Window desiredHdrHeadroom}</p>
+ *
* @param desiredHeadroom The amount of HDR headroom that is desired. Must be >= 1.0 (no HDR)
* and <= 10,000.0. Passing 0.0 will reset to the default, automatically
* chosen value.
diff --git a/core/java/android/view/Window.java b/core/java/android/view/Window.java
index 0582afe..cbee563 100644
--- a/core/java/android/view/Window.java
+++ b/core/java/android/view/Window.java
@@ -1334,6 +1334,9 @@
* <p>The requested color mode is not guaranteed to be honored. Please refer to
* {@link #getColorMode()} for more information.</p>
*
+ * <p>Note: This does not impact SurfaceViews or SurfaceControls, as those have their own
+ * independent color mode and HDR parameters.</p>
+ *
* @see #getColorMode()
* @see Display#isWideColorGamut()
* @see Configuration#isScreenWideColorGamut()
@@ -1361,6 +1364,9 @@
* See {@link Display#getHdrSdrRatio()} for more information as well as how to query the
* current value.</p>
*
+ * <p>Note: This does not impact SurfaceViews or SurfaceControls, as those have their own
+ * independent desired HDR headroom and HDR capabilities.</p>
+ *
* @param desiredHeadroom The amount of HDR headroom that is desired. Must be >= 1.0 (no HDR)
* and <= 10,000.0. Passing 0.0 will reset to the default, automatically
* chosen value.