259. PPU 时序计数器

实现基本的 PPU 时序计数器。

第 259 / 356 · tests/chapter_04_ppu_timing_and_vblank/test_259_ppu_timing_counters.py

参考资料

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

需要更新的文件

emulator/ppu/ppu.py

需要添加的常量

PPU_CYCLES_PER_SCANLINE = 341
PPU_SCANLINES_PER_FRAME = 262

需要添加的状态

cycle: int = 0
scanline: int = 0
frame: int = 0

需要添加的方法

PPU.step(cycles: int = 1) -> None

为什么需要这一步

PPU 是一个基于时间的设备。之后,VBlank、NMI、渲染以及帧节奏都要依赖于知道 PPU 当前处于这一帧内的什么位置。

在这一步,只需要添加计数器

cycle    -> position inside the current scanline
scanline -> current scanline inside the frame
frame    -> completed frame count

初始的时序模型

341 PPU cycles per scanline
262 scanlines per frame

建议的实现示例

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

未来的兼容性

这些测试有意只检查计数器的行为,暂时不要求精确的 VBlank/NMI 副作用。之后的步骤可能会在 PPU.step() 内部添加这些副作用,但这些计数器的不变式应该始终成立。

不在本步骤范围内

VBlank 的产生
NMI 请求
渲染
0 号精灵命中(sprite 0 hit)
精灵溢出
奇数帧的周期跳过

运行本课

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

示例实现

建议的实现示例

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

查看测试代码test_259_ppu_timing_counters.py

from emulator.ppu.ppu import PPU, PPU_CYCLES_PER_SCANLINE, PPU_SCANLINES_PER_FRAME, VBLANK_STARTED


def test_ppu_declares_basic_timing_constants():
    """
    Objective:
    Name the initial timing constants used by the PPU counters.
    """
    assert PPU_CYCLES_PER_SCANLINE == 341
    assert PPU_SCANLINES_PER_FRAME == 262


def test_ppu_timing_counters_start_at_zero():
    """
    Objective:
    A new PPU starts at the beginning of frame 0, scanline 0, cycle 0.
    """
    ppu = PPU()

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


def test_ppu_step_advances_one_cycle_by_default():
    """
    Objective:
    Calling step() with no argument advances one PPU cycle.
    """
    ppu = PPU()

    ppu.step()

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


def test_ppu_step_can_advance_multiple_cycles():
    """
    Objective:
    PPU.step(cycles) can advance more than one PPU cycle.

    This makes later CPU integration easier, because one CPU cycle corresponds to
    three PPU cycles.
    """
    ppu = PPU()

    ppu.step(12)

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


def test_ppu_step_wraps_cycle_and_advances_scanline_after_341_cycles():
    """
    Objective:
    After 341 PPU cycles, the PPU moves to the next scanline and cycle resets.
    """
    ppu = PPU()

    ppu.step(PPU_CYCLES_PER_SCANLINE)

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


def test_ppu_step_preserves_remaining_cycle_after_scanline_wrap():
    """
    Objective:
    Extra cycles after a scanline wrap should remain in the next scanline.

    Example:
        342 cycles = 1 full scanline + 1 cycle
    """
    ppu = PPU()

    ppu.step(PPU_CYCLES_PER_SCANLINE + 1)

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


def test_ppu_step_wraps_scanline_and_advances_frame_after_262_scanlines():
    """
    Objective:
    After 262 scanlines, the PPU starts the next 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


def test_ppu_timing_step_does_not_require_vblank_behavior_yet():
    """
    Objective:
    Step 259 only introduces counters. VBlank side effects are added in the next
    step, so this test keeps current scope narrow.

    Future compatibility:
    This test does not step far enough to reach VBlank timing. Later VBlank logic
    can be added without breaking this assertion.
    """
    ppu = PPU()

    ppu.step(10)

    assert (ppu.status & VBLANK_STARTED) == 0

测试函数 (8)

test_ppu_declares_basic_timing_constants
test_ppu_timing_counters_start_at_zero
test_ppu_step_advances_one_cycle_by_default
test_ppu_step_can_advance_multiple_cycles
test_ppu_step_wraps_cycle_and_advances_scanline_after_341_cycles
test_ppu_step_preserves_remaining_cycle_after_scanline_wrap
test_ppu_step_wraps_scanline_and_advances_frame_after_262_scanlines
test_ppu_timing_step_does_not_require_vblank_behavior_yet