260. 基于时序生成 PPU 的 VBlank

基于 PPU 时序实现 VBlank 的生成。

第 260 / 356 · tests/chapter_04_ppu_timing_and_vblank/test_260_ppu_vblank_generation_from_timing.py

参考资料

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

需要更新的文件

emulator/ppu/ppu.py

需要添加的常量

PPU_VBLANK_START_SCANLINE = 241
PPU_PRE_RENDER_SCANLINE = 261

为什么需要这一步

许多 NES 程序在写入 PPU 内存之前会等待 VBlank。它们通常会轮询 PPUSTATUS($2002),直到第 7 位被置位。

本教程步骤的概念性行为

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

这样可以在还没有实现完整渲染的情况下,给 ROM 提供一个基本的帧信号。

建议的实现示例

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

重要的简化说明

这并不是逐点精确的 PPU 时序。在真实硬件上,状态变化发生在具体的 PPU 点(dot)/周期上,通常建模在相关扫描线的第 1 个点/周期附近。目前,本教程使用的是“进入扫描线时”的行为方式,因为目标是先讲清楚帧/VBlank 的概念,之后再追求完整的周期精度。

目前不属于本教程目标的内容

逐点/逐周期精确的 VBlank 时序
奇数帧的周期跳过
在可见扫描线期间渲染像素
0 号精灵命中(sprite 0 hit)
精灵溢出
NMI 的产生/CPU 中断处理

运行本课

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

示例实现

建议的实现示例

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

查看测试代码test_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

测试函数 (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