wiki: Document the redraw loop

wiki/Redraw-Loop.md

@@ -0,0 +1,20 @@
+On a TTY, only one frame can be submitted to an output at a time, and the compositor must wait until the output repaints (indicated by a VBlank) to be able to submit the next frame.
+In niri we keep track of this via the `RedrawState` enum that you can find in an `OutputState`.
+
+Here's a diagram of state transitions for the `RedrawState` state machine:
+
+![RedrawState state transition diagram](./img/RedrawState-light.drawio.png#gh-light-mode-only)
+![RedrawState state transition diagram](./img/RedrawState-dark.drawio.png#gh-dark-mode-only)
+
+`Idle` is the default state, when the output does not need to be repainted.
+Any operation that may cause the screen to update calls `queue_redraw()`, which moves the output to a `Queued` state.
+Then, at the end of an event loop dispatch, niri calls `redraw()` for every `Queued` output.
+
+If the redraw causes damage (i.e. something on the output changed), we move into the `WaitingForVBlank` state, since we cannot redraw until we receive a VBlank event.
+However, if there's no damage, we do not return to `Idle` right away.
+Instead, we set a timer to fire roughly at when the next VBlank would occur, and transition to a `WaitingForEstimatedVBlank` state.
+
+This is necessary in order to throttle frame callbacks sent to applications to at most once per output refresh cycle.
+Without this throttling, applications can start continuously redrawing without damage (for instance, if the application window is partially off-screen, and it is only the off-screen part that changes), and eating a lot of CPU in the process.
+
+Then, either the estimated VBlank timer completes, and we go back to `Idle`, or maybe we call `queue_redraw()` once more and try to redraw again.

wiki/_Sidebar.md

@@ -25,3 +25,4 @@
 * [Design Principles](./Design-Principles.md)
 * [Developing niri](./Developing-niri.md)
 * [Fractional Layout](./Fractional-Layout.md)
+* [Redraw Loop](./Redraw-Loop.md)

wiki/img/RedrawState-dark.drawio.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d6053eb3d7dbc07ae4b03403a28819788be50ce56f1d3c109b755e50de14ad62
+size 97565

wiki/img/RedrawState-light.drawio.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:546c4a452f964f07a8d7e100eb6a007fec856c784857c67d214727b62b14a75d
+size 86906