surface_control.h: Clarify callback documentation
In response to API council feedback we more clearly
document the differences between the OnCommit and the
OnComplete callbacks.
Fixes: 187846583
Test: Doc changes only
Change-Id: Ib0529d7d01de046ccae8f14c8bf8bb9a6110624d
diff --git a/include/android/surface_control.h b/include/android/surface_control.h
index f6c2e55..644efd9 100644
--- a/include/android/surface_control.h
+++ b/include/android/surface_control.h
@@ -133,6 +133,9 @@
* ASurfaceTransaction_OnComplete callback can be used to be notified when a frame
* including the updates in a transaction was presented.
*
+ * Buffers which are replaced or removed from the scene in the transaction invoking
+ * this callback may be reused after this point.
+ *
* \param context Optional context provided by the client that is passed into
* the callback.
*
@@ -153,6 +156,13 @@
* are ready to be presented. This callback will be invoked before the
* ASurfaceTransaction_OnComplete callback.
*
+ * This callback does not mean buffers have been released! It simply means that any new
+ * transactions applied will not overwrite the transaction for which we are receiving
+ * a callback and instead will be included in the next frame. If you are trying to avoid
+ * dropping frames (overwriting transactions), and unable to use timestamps (Which provide
+ * a more efficient solution), then this method provides a method to pace your transaction
+ * application.
+ *
* \param context Optional context provided by the client that is passed into the callback.
*
* \param stats Opaque handle that can be passed to ASurfaceTransactionStats functions to query