260. Generación de VBlank de la PPU a partir de la temporización

Implementa la generación de VBlank a partir de la temporización de la PPU.

Lección 260 de 356 · tests/chapter_04_ppu_timing_and_vblank/test_260_ppu_vblank_generation_from_timing.py

Referencia

https://www.nesdev.org/wiki/PPU_rendering#Line-by-line_timing
https://www.nesdev.org/wiki/PPU_registers#PPUSTATUS

Archivo a modificar

emulator/ppu/ppu.py

Constantes a añadir

PPU_VBLANK_START_SCANLINE = 241
PPU_PRE_RENDER_SCANLINE = 261

Por qué existe este paso

Muchos programas de NES esperan a VBlank antes de escribir en la memoria de la PPU. Habitualmente sondean PPUSTATUS ($2002) hasta que el bit 7 se activa.

Comportamiento conceptual para este paso del tutorial

when the PPU enters scanline 241:
    set PPUSTATUS bit 7, VBLANK_STARTED

when the PPU enters scanline 261, the pre-render scanline:
    clear PPUSTATUS bit 7

Esto proporciona a las ROMs una señal básica de fotograma sin implementar todavía el renderizado completo.

Ejemplo de implementación sugerida

PPU_VBLANK_START_SCANLINE = 241
PPU_PRE_RENDER_SCANLINE = 261

def step(self, cycles: int = 1) -> None:
    for _ in range(cycles):
        self.cycle += 1

        if self.cycle >= PPU_CYCLES_PER_SCANLINE:
            self.cycle = 0
            self.scanline += 1

            if self.scanline >= PPU_SCANLINES_PER_FRAME:
                self.scanline = 0
                self.frame += 1

            # Simplified scanline-level timing event.
            if self.scanline == PPU_VBLANK_START_SCANLINE:
                self.status |= VBLANK_STARTED

            if self.scanline == PPU_PRE_RENDER_SCANLINE:
                self.status &= ~VBLANK_STARTED

Simplificación importante

Esto no es una temporización de la PPU exacta por dot. En el hardware real, los cambios de estado ocurren en dots/ciclos concretos de la PPU, habitualmente modelados en torno al dot/ciclo 1 de la línea de barrido correspondiente. Por ahora, este tutorial usa un comportamiento de entrada de línea de barrido porque el objetivo es enseñar el concepto de fotograma/VBlank antes de la precisión total por ciclo.

Fuera de los objetivos del tutorial por ahora

temporización de VBlank precisa por dot/ciclo
salto de ciclo en fotograma impar
renderizado de píxeles durante las líneas de barrido visibles
sprite 0 hit
desbordamiento de sprites
generación de NMI/gestión de interrupciones de la CPU

Ejecutar esta lección

uv run pytest tests/chapter_04_ppu_timing_and_vblank/test_260_ppu_vblank_generation_from_timing.py -v

Implementación de ejemplo

Ejemplo de implementación sugerida

PPU_VBLANK_START_SCANLINE = 241
PPU_PRE_RENDER_SCANLINE = 261

def step(self, cycles: int = 1) -> None:
    for _ in range(cycles):
        self.cycle += 1

        if self.cycle >= PPU_CYCLES_PER_SCANLINE:
            self.cycle = 0
            self.scanline += 1

            if self.scanline >= PPU_SCANLINES_PER_FRAME:
                self.scanline = 0
                self.frame += 1

            # Simplified scanline-level timing event.
            if self.scanline == PPU_VBLANK_START_SCANLINE:
                self.status |= VBLANK_STARTED

            if self.scanline == PPU_PRE_RENDER_SCANLINE:
                self.status &= ~VBLANK_STARTED

Ver código del testtest_260_ppu_vblank_generation_from_timing.py

from emulator.ppu.ppu import (
    PPU,
    PPU_CYCLES_PER_SCANLINE,
    PPU_PRE_RENDER_SCANLINE,
    PPU_SCANLINES_PER_FRAME,
    PPU_VBLANK_START_SCANLINE,
    VBLANK_STARTED,
)


def cycles_to_enter_scanline(scanline: int) -> int:
    """Return the number of PPU cycles needed to enter a scanline from reset."""
    return PPU_CYCLES_PER_SCANLINE * scanline


def test_ppu_declares_vblank_timing_scanline_constants():
    """
    Objective:
    Name the scanlines used by the simplified VBlank timing model.
    """
    assert PPU_VBLANK_START_SCANLINE == 241
    assert PPU_PRE_RENDER_SCANLINE == 261


def test_vblank_is_clear_before_vblank_start_scanline():
    """
    Objective:
    Before entering scanline 241, PPUSTATUS VBlank bit should still be clear.
    """
    ppu = PPU()

    ppu.step(cycles_to_enter_scanline(PPU_VBLANK_START_SCANLINE) - 1)

    assert ppu.scanline == PPU_VBLANK_START_SCANLINE - 1
    assert (ppu.status & VBLANK_STARTED) == 0


def test_vblank_starts_when_ppu_enters_scanline_241():
    """
    Objective:
    Entering the VBlank start scanline sets PPUSTATUS bit 7.

    Tutorial simplification:
    This checks scanline-level behavior, not exact dot/cycle-1 timing.
    """
    ppu = PPU()

    ppu.step(cycles_to_enter_scanline(PPU_VBLANK_START_SCANLINE))

    assert ppu.scanline == PPU_VBLANK_START_SCANLINE
    assert ppu.cycle == 0
    assert (ppu.status & VBLANK_STARTED) != 0


def test_vblank_remains_set_during_vblank_until_cleared():
    """
    Objective:
    After VBlank starts, the flag remains set while the PPU continues through
    later VBlank scanlines.
    """
    ppu = PPU()

    ppu.step(cycles_to_enter_scanline(PPU_VBLANK_START_SCANLINE))
    ppu.step(PPU_CYCLES_PER_SCANLINE * 3)

    assert ppu.scanline == PPU_VBLANK_START_SCANLINE + 3
    assert (ppu.status & VBLANK_STARTED) != 0


def test_ppustatus_read_clears_vblank_and_timing_does_not_reset_it_same_scanline():
    """
    Objective:
    Reading PPUSTATUS should clear VBlank. Because VBlank is generated only when
    entering scanline 241, stepping more cycles on that same scanline should not
    immediately set it again.

    This protects against treating VBlank as "always true during scanline 241".
    """
    ppu = PPU()

    ppu.step(cycles_to_enter_scanline(PPU_VBLANK_START_SCANLINE))
    assert (ppu.status & VBLANK_STARTED) != 0

    value = ppu.read_register(0x2002)
    assert (value & VBLANK_STARTED) != 0
    assert (ppu.status & VBLANK_STARTED) == 0

    ppu.step(10)

    assert ppu.scanline == PPU_VBLANK_START_SCANLINE
    assert (ppu.status & VBLANK_STARTED) == 0


def test_pre_render_scanline_clears_vblank():
    """
    Objective:
    Entering the pre-render scanline clears the VBlank flag.
    """
    ppu = PPU()

    ppu.step(cycles_to_enter_scanline(PPU_VBLANK_START_SCANLINE))
    assert (ppu.status & VBLANK_STARTED) != 0

    ppu.step(PPU_CYCLES_PER_SCANLINE * (PPU_PRE_RENDER_SCANLINE - PPU_VBLANK_START_SCANLINE))

    assert ppu.scanline == PPU_PRE_RENDER_SCANLINE
    assert (ppu.status & VBLANK_STARTED) == 0


def test_vblank_generation_still_allows_frame_wrap():
    """
    Objective:
    Adding VBlank side effects should not break the timing counter invariant that
    262 scanlines complete one frame.
    """
    ppu = PPU()

    ppu.step(PPU_CYCLES_PER_SCANLINE * PPU_SCANLINES_PER_FRAME)

    assert ppu.cycle == 0
    assert ppu.scanline == 0
    assert ppu.frame == 1

Funciones de test (7)

test_ppu_declares_vblank_timing_scanline_constants
test_vblank_is_clear_before_vblank_start_scanline
test_vblank_starts_when_ppu_enters_scanline_241
test_vblank_remains_set_during_vblank_until_cleared
test_ppustatus_read_clears_vblank_and_timing_does_not_reset_it_same_scanline
test_pre_render_scanline_clears_vblank
test_vblank_generation_still_allows_frame_wrap