Add support for restricting HDR headroom for video
This is needed for allowing apps to vote for HDR headroom restrictions
for SurfaceView and SurfaceControl
Bug: 323964760
Test: manually poking at test app
Test: SurfaceViewTests
Test: SurfaceControlTest
Test: ASurfaceControlTest
Change-Id: Ie886e67879525462d49fdedc535aea659d69321a
diff --git a/include/android/surface_control.h b/include/android/surface_control.h
index cce2e46..321737e 100644
--- a/include/android/surface_control.h
+++ b/include/android/surface_control.h
@@ -528,9 +528,8 @@
/**
* Sets the desired extended range brightness for the layer. This only applies for layers whose
- * dataspace has RANGE_EXTENDED set on it.
- *
- * Available since API level 34.
+ * dataspace has RANGE_EXTENDED set on it. See: ASurfaceTransaction_setDesiredHdrHeadroom, prefer
+ * using this API for formats that encode an HDR/SDR ratio as part of generating the buffer.
*
* @param surface_control The layer whose extended range brightness is being specified
* @param currentBufferRatio The current hdr/sdr ratio of the current buffer as represented as
@@ -564,6 +563,12 @@
* determined entirely by the dataspace being used (ie, typically SDR
* however PQ or HLG transfer functions will still result in HDR)
*
+ * When called after ASurfaceTransaction_setDesiredHdrHeadroom, the
+ * desiredRatio will override the desiredHeadroom provided by
+ * ASurfaceTransaction_setDesiredHdrHeadroom. Conversely, when called before
+ * ASurfaceTransaction_setDesiredHdrHeadroom, the desiredHeadroom provided by
+ *. ASurfaceTransaction_setDesiredHdrHeadroom will override the desiredRatio.
+ *
* Must be finite && >= 1.0f
*
* Available since API level 34.
@@ -574,6 +579,45 @@
float desiredRatio) __INTRODUCED_IN(__ANDROID_API_U__);
/**
+ * Sets the desired hdr headroom for the layer. See: ASurfaceTransaction_setExtendedRangeBrightness,
+ * prefer using this API for formats that conform to HDR standards like HLG or HDR10, that do not
+ * communicate a HDR/SDR ratio as part of generating the buffer.
+ *
+ * @param surface_control The layer whose desired hdr headroom is being specified
+ *
+ * @param desiredHeadroom The desired hdr/sdr ratio as represented as peakHdrBrightnessInNits /
+ * targetSdrWhitePointInNits. This can be used to communicate the max
+ * desired brightness range of the panel. The system may not be able to, or
+ * may choose not to, deliver the requested range.
+ *
+ * While requesting a large desired ratio will result in the most
+ * dynamic range, voluntarily reducing the requested range can help
+ * improve battery life as well as can improve quality by ensuring
+ * greater bit depth is allocated to the luminance range in use.
+ *
+ * Default value is 0.0f and indicates that the system will choose the best
+ * headroom for this surface control's content. Typically, this means that
+ * HLG/PQ encoded content will be displayed with some HDR headroom greater
+ * than 1.0.
+ *
+ * When called after ASurfaceTransaction_setExtendedRangeBrightness, the
+ * desiredHeadroom will override the desiredRatio provided by
+ * ASurfaceTransaction_setExtendedRangeBrightness. Conversely, when called
+ * before ASurfaceTransaction_setExtendedRangeBrightness, the desiredRatio
+ * provided by ASurfaceTransaction_setExtendedRangeBrightness will override
+ * the desiredHeadroom.
+ *
+ * Must be finite && >= 1.0f or 0.0f to indicate there is no desired
+ * headroom.
+ *
+ * Available since API level 35.
+ */
+void ASurfaceTransaction_setDesiredHdrHeadroom(ASurfaceTransaction* transaction,
+ ASurfaceControl* surface_control,
+ float desiredHeadroom)
+ __INTRODUCED_IN(__ANDROID_API_V__);
+
+/**
* Same as ASurfaceTransaction_setFrameRateWithChangeStrategy(transaction, surface_control,
* frameRate, compatibility, ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS).
*