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
переполнение спрайтов
пропуск цикла нечётного кадра

Запустить этот урок

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