Clean up rendering overview (first pass)

Author: ISSOtm

src/Rendering.md

@@ -17,67 +17,52 @@ The following diagram shows how a Game Boy frame is decomposed:
 
 </figure>
 
-## STAT modes
+TODO: high-level description of the above... and implications ("raster effects")
 
-The LCD controller operates on a 2^22 Hz = 4.194 MHz dot clock. An
-entire frame is 154 scanlines = 70224 dots = 16.74 ms. On scanlines 0
+## PPU modes
+
+The PPU operates on a 2<sup>22</sup> Hz = 4.194 MHz clock, called the "dot clock".
+An entire frame is 154 scanlines = 70224 dots = 16.74 ms. On scanlines 0
 through 143, the PPU cycles through modes 2, 3, and 0 once
 every 456 dots. Scanlines 144 through 153 are mode 1.
 
-The following sequence is typical when the display is enabled:
+While the PPU is accessing some video-related memory, [that memory is inaccessible to the CPU](<#Accessing VRAM and OAM>) (writes are ignored, and reads return garbage values, usually $FF).
 
-```
-Mode 2  2_____2_____2_____2_____2_____2___________________2____
-Mode 3  _33____33____33____33____33____33__________________3___
-Mode 0  ___000___000___000___000___000___000________________000
-Mode 1  ____________________________________11111111111111_____
-```
+Mode | Action                                     | Duration                             | Accessible video memory
+-----|--------------------------------------------|--------------------------------------|-------------------------
+  2  | Searching for OBJs which overlap this line | 80 dots                              | VRAM, CGB palettes
+  3  | Sending pixels to the LCD                  | Between 172 and 289 dots, see below  | None
+  0  | Waiting until the end of the scanline      | 376 - mode 3's duration              | VRAM, OAM, CGB palettes
+  1  | Waiting until the next frame               | 4560 dots (10 scanlines)             | VRAM, OAM, CGB palettes
 
-When the PPU is accessing some video-related memory, that memory is inaccessible
-to the CPU: writes are ignored, and reads return garbage values (usually $FF).
+## Mode 3 length
 
-- During modes 2 and 3, the CPU cannot access [OAM](<#VRAM Sprite Attribute Table (OAM)>) ($FE00-FE9F).
-- During mode 3, the CPU cannot access VRAM or [CGB palette data registers](<#LCD Color Palettes (CGB only)>)
-  ($FF69,$FF6B).
+Unlike most game consoles, the Game Boy does not always output pixels steadily[^crt]: some features cause the rendering process to stall for a couple dots.
+Any extra time spent stalling *lengthens* Mode 3; but since scanlines last for a fixed number of dots, Mode 0 is therefore shortened by that same amount of time.
 
-Mode | Action                                                      | Duration                                                           | Accessible video memory
------|------------------------------------------------------------------|--------------------------------------------------------------------|-------------------------
-  2  | Searching OAM for OBJs whose Y coordinate overlap this line | 80 dots                                               | VRAM, CGB palettes
-  3  | Reading OAM and VRAM to generate the picture                | 168 to 291 dots, depending on object count            | None
-  0  | Nothing (HBlank)                                            | 85 to 208 dots, depending on previous mode 3 duration | VRAM, OAM, CGB palettes
-  1  | Nothing (VBlank)                                            | 4560 dots (10 scanlines)                              | VRAM, OAM, CGB palettes
+Three things can cause Mode 3 "penalties":
 
-## Properties of STAT modes
+- **Background scrolling**: At the very beginning of Mode 3, rendering is paused for [`SCX`](<#FF42–FF43 — SCY, SCX: Viewport Y position, X position>) % 8 dots while the same number of pixels are discarded from the leftmost tile.
+- **Window**: After the last non-window pixel is emitted, a 6-dot penalty is incurred while the BG fetcher is being set up for the window.
+- **Objects**: Each object drawn during the scanline (even partially) incurs a 6- to 11-dot penalty ([see below](<#OBJ penalty algorithm>)).
 
-Unlike most game consoles, the Game Boy can pause the dot clock briefly,
-making Mode 3 longer and Mode 0 shorter. It routinely takes a 6 to 11 dot
-break to fetch an OBJ's tile between background tile pattern fetches.
 On DMG and GBC in DMG mode, mid-scanline writes to [`BGP`](<#FF47 — BGP (Non-CGB Mode only): BG palette data>)
 allow observing this behavior, as the delay from drawing an OBJ shifts the
 write's effect to the left by that many dots.
 
-Three things are known to pause the dot clock:
-
-- Background scrolling: If `SCX % 8` is not zero at the start of the scanline, rendering is paused for that many dots while the shifter discards that many pixels from the leftmost tile.
-- Window: An active window pauses for at least 6 dots, as the background fetching mechanism starts over at the left side of the window.
-- Objects: Each object usually pauses for `11 - min(5, (x + SCX) % 8)` dots.
-  Because object fetch waits for background fetch to finish, an object's cost depends on its position relative to the left side of the background tile under it. It's greater if an object is directly aligned over the background tile, less if the object is to the right. If the object's left side is over the window, use `255 - WX` instead of `SCX` in this formula.
+### OBJ penalty algorithm
 
-::: warning TO BE VERIFIED
+Only the OBJ's leftmost pixel matters here, transparent or not; it is designated as "The Pixel" in the following.
 
-The exact pause duration for window start is
-not confirmed; it may have the same background fetch finish delay as
-an object. If two objects' left sides are over the same background or
-window tile, the second may pause for fewer dots.
+1. Determine the tile (background or window) that The Pixel is within. (This is affected by horizontal scrolling and/or the window!)
+2. If that tile has **not** been considered by a previous OBJ yet:
+   1. Count how many of that tile's pixels are to the right of The Pixel.
+   2. Subtract 3.
+   3. Incur this many dots of penalty, or zero if negative (from waiting for the BG fetch to finish).
+3. Incur a flat, 6-dot penalty (from fetching the OBJ's tile).
 
-:::
+**Exception**: an OBJ with an OAM X position of 0 (thus, completely off the left side of the screen) always incurs a 11-cycle penalty, regardless of `SCX`.
 
-A hardware quirk in the monochrome Game Boy makes the LCD interrupt
-sometimes trigger when writing to STAT (including writing \$00) during
-OAM scan, HBlank, VBlank, or LY=LYC. It behaves as if \$FF were
-written for one cycle, and then the written value were written the next
-cycle. Because the GBC in DMG mode does not have this quirk, two games
-that depend on this quirk (Ocean's *Road Rash* and Vic Tokai's *Xerd
-no Densetsu*) will not run on a GBC.
+TODO: a diagram of some examples would probably help this be much clearer! \>_\<
 
-TODO
+[^crt]: The Game Boy can afford to "take pauses", because it writes to a LCD it fully controls; by contrast, home consoles like the NES or SNES are on a schedule imposed by the screen they are hooked up to. Taking pauses arguably simplified the PPU's design while allowing greater flexibility to game developers.

src/STAT.md

@@ -39,3 +39,13 @@ Bit 2 is set when [LY](<#FF44 — LY: LCD Y coordinate \[read-only\]>) contains
 It is constantly updated.
 
 Bits 3-6 select which sources are used for [the STAT interrupt](<#INT $48 — STAT interrupt>).
+
+### Spurious STAT interrupts
+
+A hardware quirk in the monochrome Game Boy makes the LCD interrupt
+sometimes trigger when writing to STAT (including writing \$00) during
+OAM scan, HBlank, VBlank, or LY=LYC. It behaves as if \$FF were
+written for one cycle, and then the written value were written the next
+cycle. Because the GBC in DMG mode does not have this quirk, two games
+that depend on this quirk (Ocean's *Road Rash* and Vic Tokai's *Xerd
+no Densetsu*) will not run on a GBC.