hwc2: Fix readback docsandroid-9.0.0_r47android-9.0.0_r46android-9.0.0_r45android-9.0.0_r44android-9.0.0_r43android-9.0.0_r42android-9.0.0_r41android-9.0.0_r40android-9.0.0_r39android-9.0.0_r38android-9.0.0_r37android-9.0.0_r36android-9.0.0_r35android-9.0.0_r34android-9.0.0_r33android-9.0.0_r32android-9.0.0_r31android-9.0.0_r30android-9.0.0_r22android-9.0.0_r21android-9.0.0_r20android-9.0.0_r19android-9.0.0_r16android-9.0.0_r12android-9.0.0_r11pie-qpr3-s1-releasepie-qpr3-releasepie-qpr3-b-releasepie-qpr2-releasepie-qpr1-s3-releasepie-qpr1-s2-releasepie-qpr1-s1-releasepie-qpr1-releasepie-dr1-releasepie-dr1-devpie-devpie-b4s4-releasepie-b4s4-dev

Fixes a couple of problems with the return codes in the readback
documentation and adds a paragraph of clarification about when
getReadbackBufferAttributes will be called.

Bug: 67048889
Test: N/A, doc fix only
Change-Id: I3ea1a6993323f7ce12c36a377bf69e2866b18082

1 files changed, 13 insertions, 5 deletions

diff --git a/include/hardware/hwcomposer2.h b/include/hardware/hwcomposer2.h
index 0138cbb0..c9809ce8 100644
--- a/include/hardware/hwcomposer2.h
+++ b/include/hardware/hwcomposer2.h
@@ -1774,15 +1774,19 @@ typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_POWER_MODE)(
  * output of the display remains the same (subject to the note about protected
  * content in the description of setReadbackBuffer).
  *
+ * If the active configuration or color mode of this display has changed since
+ * the previous call to this function, it will be called again prior to setting
+ * a readback buffer such that the returned format and dataspace can be updated
+ * accordingly.
+ *
  * Parameters:
  *   outFormat - the format the client should use when allocating a device
- *       readback buffer
+ *       readback buffer; pointer will be non-NULL
  *   outDataspace - the dataspace the client will use when interpreting the
- *       contents of a device readback buffer
+ *       contents of a device readback buffer; pointer will be non-NULL
  *
  * Returns HWC2_ERROR_NONE or one of the following errors:
  *   HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
- *   HWC2_ERROR_UNSUPPORTED - mode was a valid power mode, but is not supported
  *
  * See also:
  *   setReadbackBuffer
@@ -1824,8 +1828,12 @@ typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_READBACK_BUFFER_ATTRIBUTES)(
  *
  * Returns HWC2_ERROR_NONE or one of the following errors:
  *   HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
- *   HWC2_ERROR_UNSUPPORTED - mode was a valid power mode, but is not supported
- *
+ *   HWC2_ERROR_NO_RESOURCES - the readback operation was successful, but
+ *       resulted in a different validate result than would have occurred
+ *       without readback
+ *   HWC2_ERROR_UNSUPPORTED - the readback operation was unsuccessful because
+ *       of resource constraints, the presence of protected content, or other
+ *       reasons; -1 must be returned in outFence
  */
 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_READBACK_BUFFER_FENCE)(
         hwc2_device_t* device, hwc2_display_t display,