Merge "Buffer Stuffing documentation for dequeueBuffer" into main

Author: Melody Hsu

libs/gui/BufferStuffing.md

@@ -2,6 +2,6 @@
 
 Buffer stuffing happens on the client side when SurfaceFlinger misses a frame, but the client continues producing buffers at the same rate. This could occur anytime when SurfaceFlinger does not meet the expected timeline’s deadline to finish composing a frame. As a result, SurfaceFlinger cannot yet release the buffer for the frame that it missed and the client has one less buffer to render into. The client may then run out of buffers or have to wait for buffer release callbacks, increasing the chances of janking when clients render multiple windows.
 
-Recovery is implemented by first detecting when buffer stuffing occurs and ensuring that the elevated buffer counts in the server are from a relevant SurfaceControl (is a ViewRootImpl). Other SurfaceControl buffer producers such as games, media, and camera have other reasons for expectedly increased buffer counts, which do not need buffer stuffing recovery.
+Buffer stuffing is first detected through a callback when RenderThread is blocked in BlastBufferQueue#dequeueBuffer, where an app may wait for a buffer to become available. When RenderThread is blocked on dequeueBuffer, the system is maximally stuffed as there are no available buffers and is vulnerable to additional jank. The callback provides the duration spent blocked in dequeueBuffer, which is used to guard against potential false positives that might result from slight variations in buffer release timing. As there is one BlastBufferQueue associated with the SurfaceControl on the root window, waiting for the buffer release callback here also filters out other SurfaceControl buffer producers that do not require buffer stuffing recovery, such as games, media, and camera. These other buffer producers may have expectedly higher buffer counts because they can queue up more buffers in advance to meet high throughput, low latency requirements. For example, a video might queue up as many buffers as possible in preparation for the upcoming frames. It would be considered acceptable for it to be stuffed in this case because it is not affecting other CUJs and the stuffing helps prepare the rendering pipeline.
 
-The actual recovery adjusts the animation timeline in the Choreographer so that the client deadlines for subsequent frames are moved forward in time by one frame. This approach adjusts the client buffer production timeline such that SurfaceFlinger does not fall behind when it misses a frame because the client will simply match its frame production rate with SurfaceFlinger. Ordinarily, buffer stuffing is problematic because the client continues producing buffers when SurfaceFlinger is behind. However, if the client delays producing its buffers to match SurfaceFlinger’s rate, the animation has new frame deadlines that can be reasonably met. The animation is effectively paused for one frame longer than originally intended, and continues the remainder of the animation normally.
+The actual recovery adjusts the animation timeline in the Choreographer so that the client deadlines for subsequent frames are moved forward in time by one frame. This approach adjusts the client buffer production timeline such that SurfaceFlinger does not fall behind when it misses a frame because the client will simply match its frame production rate with SurfaceFlinger. Ordinarily, buffer stuffing is problematic because the client continues producing buffers when SurfaceFlinger is behind. However, if the client delays producing its buffers to match SurfaceFlinger’s rate, the animation has new frame deadlines that can be reasonably met. The animation is effectively paused for one frame longer than originally intended, and continues the remainder of the animation normally. At most one frame (and one buffer) is delayed per stuffing event, meaning that if the client janks again after recovery has started and before its animation ends, no additional recovery attempts are made.