class ReleaseFenceManager

ReleaseFenceManager is a helper which encapsulates the logic for signaling release fences, and

for invoking frame-presented callbacks according to the contract with FrameScheduler.

=== Design Requirements for signaling client release fences ===

Client release fences are signaled as soon as it is safe to do so without risking visual

artifacts. The time that it becomes safe depends on whether a frame is GPU-composited or

direct-scanout.

GPU-composition case: fences can be signaled as soon as Vulkan is finished rendering the frame.

Direct-scanout case: client images are directly read by the display controller, and so the fences

cannot be signaled until the *next* frame is displayed on-screen.

ReleaseFenceManager handles these cases separately, in order to minimize the latency before

clients can reuse their images.

=== Design Requirements for invoking FramePresentedCallback ===

The contract with FrameScheduler requires that these callbacks are invoked in the order that they

are received. As a result, callback invocation may be delayed even though all of the information

required by the callback is known (i.e. render-finished time and frame-presented time), when an

earlier callback is not yet ready to invoke.

For example, this can happen when a GPU-composited frame misses a vsync because rendering is

still not finished, even though the subsequent direct-scanout frame is already on the screen.

Ordinarily, the callback for the second frame could be invoked, but in this scenario it cannot

because it must wait for the first callback to be invoked, which must wait until Vulkan signals

the render-finished fence.

=== Usage ===

ReleaseFenceManager is very simple to use. Each frame, the caller (typically DisplayCompositor)

calls either OnGpuCompositedFrame() or OnDirectScanoutFrame(). The caller has two other

responsibilities:

1) for GPU-composited frames, to signal the |render_finished_event| (typically done via a Vulkan

semaphore).

2) to call OnVsync() when a frame is presented on the display

=== Thread Safety ===

ReleaseFenceManager is not thread-safe; methods should only be called from the "main thread",

i.e. the same thread as used by the |dispatcher| passed to the constructor. Due to the use

of this dispatcher, it is not safe to use from multiple threads even if externally

synchronized, e.g. via a mutex.