git.y1.nz

commit 25a7b2b82211bb2822a3d5e311c7311149e95870
parent 533ca107c7a68c7e8a2c7a57abf4306c33f3431c
Author: bbbbbr <bbbbbr@users.noreply.github.com>
Date:   Wed, 14 May 2025 01:16:00 -0700

Merge pull request #781 from bbbbbr/docs_4_4_0

Docs: update for NES description
Diffstat:
M
docs/api/docs_supported_consoles.html
12
+++++-------
M
docs/api/index.js
2
+-

2 files changed, 6 insertions(+), 8 deletions(-)
diff --git a/docs/api/docs_supported_consoles.html b/docs/api/docs_supported_consoles.html
@@ -568,13 +568,11 @@ Direct mode implementation details</h4>
 <p>Direct mode also affects how (fake) interrupt handlers are processed. As long as <a class="el" href="gb_8h.html#af57b77452ef377da18e4fbf0288013d1">vsync()</a> is called on each frame, the VBL and LCD handlers will still be executed in direct mode - but no graphics registers will be written.</p>
 <p>The TIM handler will still be executed as normal.</p>
 <h4><a class="anchor" id="autotoc_md181"></a>
-Caveat: Only update the PPU palette during buffered mode</h4>
-<p>The oddity that PPU palette values are accessed through the same mechanism as other PPU memory bytes comes with the side effect that the vblank NMI handler will only write the palette values in buffered mode.</p>
-<p>The reason for this design choice is two-fold:</p><ul>
-<li>Having the NMI handler keep doing the palette updates when in direct mode would result in a race condition when the NMI handler interrupts the direct mode code and messes with the PPUADDR state that the direct mode code expects to remain unchanged</li>
-<li>Having the palette updates also switch to direct mode would run into another quirk of the system: Pointing PPUADDR at palette registers when display is turned off will make the display output that palette color instead of the common background color. The result would be glitchy artifacts on screen when updating the palette, leading to a slightly-glitchy looking game whenever the palette is updated with the screen off</li>
-</ul>
-<p>To work around this, you are advised to never fully turn the display off during a palette fade. If you don't follow this advice all your palette updates will get delayed until the screen is turned back on.</p>
+Caveat: Write appropriate global backdrop before turning display off</h4>
+<p>On the GB, when the display is turned off the LCD will display a whiter-than-white color.</p>
+<p>On the NES, calling DISPLAY_OFF will turn sprites and BG off and allow VRAM writes in direct mode. But the color displayed will be last global backdrop color (i.e. palette entry 0) that was written before DISPLAY_OFF was called.</p>
+<p>Because all palette writes will be postponed in direct mode, the same also applies to other palette entries: Their values will be maintained in RAM, but never actually reach the PPU's hardware palette registers until buffered mode is re-entered by calling DISPLAY_ON.</p>
+<p>You should not try to do any palette fades after calling DISPLAY_OFF, as they will be delayed in direct mode until the display is turned on again with DISPLAY_ON. Once DISPLAY_ON is called, the NMI handler will start updating the hardware palette registers with the RAM registers as normal.</p>
 <h3><a class="anchor" id="autotoc_md182"></a>
 Shadow PPU registers</h3>
 <p>Like the SMS, the NES hardware is designed to only allow loading the full X/Y scroll on the very first scanline. i.e., under normal operation you are only allowed to change the Y-scroll once.</p>
diff --git a/docs/api/index.js b/docs/api/index.js
@@ -188,7 +188,7 @@ var index =
           [ "Buffered mode vs direct mode", "docs_supported_consoles.html#autotoc_md178", [
             [ "Buffered mode implementation details", "docs_supported_consoles.html#autotoc_md179", null ],
             [ "Direct mode implementation details", "docs_supported_consoles.html#autotoc_md180", null ],
-            [ "Caveat: Only update the PPU palette during buffered mode", "docs_supported_consoles.html#autotoc_md181", null ]
+            [ "Caveat: Write appropriate global backdrop before turning display off", "docs_supported_consoles.html#autotoc_md181", null ]
           ] ],
           [ "Shadow PPU registers", "docs_supported_consoles.html#autotoc_md182", null ],
           [ "Implementation of (fake) vbl / lcd handlers", "docs_supported_consoles.html#autotoc_md183", null ],

This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.