@@ -145,6 +145,9 @@ typedef struct ASurfaceTransactionStats ASurfaceTransactionStats;
145145 * Buffers which are replaced or removed from the scene in the transaction invoking
146146 * this callback may be reused after this point.
147147 *
148+ * Starting with API level 36, prefer using \a ASurfaceTransaction_OnBufferRelease to listen
149+ * to when a buffer is ready to be reused.
150+ *
148151 * \param context Optional context provided by the client that is passed into
149152 * the callback.
150153 *
@@ -157,8 +160,7 @@ typedef struct ASurfaceTransactionStats ASurfaceTransactionStats;
157160 * Available since API level 29.
158161 */
159162typedef void (* ASurfaceTransaction_OnComplete )(void * _Null_unspecified context ,
160- ASurfaceTransactionStats * _Nonnull stats )
161- __INTRODUCED_IN (29 );
163+ ASurfaceTransactionStats * _Nonnull stats );
162164
163165/**
164166 * The ASurfaceTransaction_OnCommit callback is invoked when transaction is applied and the updates
@@ -186,8 +188,36 @@ typedef void (*ASurfaceTransaction_OnComplete)(void* _Null_unspecified context,
186188 * Available since API level 31.
187189 */
188190typedef void (* ASurfaceTransaction_OnCommit )(void * _Null_unspecified context ,
189- ASurfaceTransactionStats * _Nonnull stats )
190- __INTRODUCED_IN (31 );
191+ ASurfaceTransactionStats * _Nonnull stats );
192+
193+ /**
194+ * The ASurfaceTransaction_OnBufferRelease callback is invoked when a buffer that was passed in
195+ * ASurfaceTransaction_setBuffer is ready to be reused.
196+ *
197+ * This callback is guaranteed to be invoked if ASurfaceTransaction_setBuffer is called with a non
198+ * null buffer. If the buffer in the transaction is replaced via another call to
199+ * ASurfaceTransaction_setBuffer, the callback will be invoked immediately. Otherwise the callback
200+ * will be invoked before the ASurfaceTransaction_OnComplete callback after the buffer was
201+ * presented.
202+ *
203+ * If this callback is set, caller should not release the buffer using the
204+ * ASurfaceTransaction_OnComplete.
205+ *
206+ * \param context Optional context provided by the client that is passed into the callback.
207+ *
208+ * \param release_fence_fd Returns the fence file descriptor used to signal the release of buffer
209+ * associated with this callback. If this fence is valid (>=0), the buffer has not yet been released
210+ * and the fence will signal when the buffer has been released. If the fence is -1 , the buffer is
211+ * already released. The recipient of the callback takes ownership of the fence fd and is
212+ * responsible for closing it.
213+ *
214+ * THREADING
215+ * The callback can be invoked on any thread.
216+ *
217+ * Available since API level 36.
218+ */
219+ typedef void (* ASurfaceTransaction_OnBufferRelease )(void * _Null_unspecified context ,
220+ int release_fence_fd );
191221
192222/**
193223 * Returns the timestamp of when the frame was latched by the framework. Once a frame is
@@ -251,7 +281,7 @@ int64_t ASurfaceTransactionStats_getAcquireTime(
251281/**
252282 * The returns the fence used to signal the release of the PREVIOUS buffer set on
253283 * this surface. If this fence is valid (>=0), the PREVIOUS buffer has not yet been released and the
254- * fence will signal when the PREVIOUS buffer has been released. If the fence is -1 , the PREVIOUS
284+ * fence will signal when the PREVIOUS buffer has been released. If the fence is -1, the PREVIOUS
255285 * buffer is already released. The recipient of the callback takes ownership of the
256286 * previousReleaseFenceFd and is responsible for closing it.
257287 *
@@ -353,13 +383,39 @@ void ASurfaceTransaction_setZOrder(ASurfaceTransaction* _Nonnull transaction,
353383 * Note that the buffer must be allocated with AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE
354384 * as the surface control might be composited using the GPU.
355385 *
386+ * Starting with API level 36, prefer using \a ASurfaceTransaction_setBufferWithRelease to
387+ * set a buffer and a callback which will be invoked when the buffer is ready to be reused.
388+ *
356389 * Available since API level 29.
357390 */
358391void ASurfaceTransaction_setBuffer (ASurfaceTransaction * _Nonnull transaction ,
359392 ASurfaceControl * _Nonnull surface_control ,
360393 AHardwareBuffer * _Nonnull buffer , int acquire_fence_fd )
361394 __INTRODUCED_IN (29 );
362395
396+ /**
397+ * Updates the AHardwareBuffer displayed for \a surface_control. If not -1, the
398+ * acquire_fence_fd should be a file descriptor that is signaled when all pending work
399+ * for the buffer is complete and the buffer can be safely read.
400+ *
401+ * The frameworks takes ownership of the \a acquire_fence_fd passed and is responsible
402+ * for closing it.
403+ *
404+ * Note that the buffer must be allocated with AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE
405+ * as the surface control might be composited using the GPU.
406+ *
407+ * When the buffer is ready to be reused, the ASurfaceTransaction_OnBufferRelease
408+ * callback will be invoked. If the buffer is null, the callback will not be invoked.
409+ *
410+ * Available since API level 36.
411+ */
412+ void ASurfaceTransaction_setBufferWithRelease (ASurfaceTransaction * _Nonnull transaction ,
413+ ASurfaceControl * _Nonnull surface_control ,
414+ AHardwareBuffer * _Nonnull buffer ,
415+ int acquire_fence_fd , void * _Null_unspecified context ,
416+ ASurfaceTransaction_OnBufferRelease _Nonnull func )
417+ __INTRODUCED_IN (36 );
418+
363419/**
364420 * Updates the color for \a surface_control. This will make the background color for the
365421 * ASurfaceControl visible in transparent regions of the surface. Colors \a r, \a g,
0 commit comments