287. Console: шаг до следующего кадра

Добавить Console.step_until_next_frame() для пошагового выполнения на уровне кадров.

Урок 287 из 356 · tests/chapter_05_rendering_pipeline/test_287_console_step_until_next_frame.py

Файл для обновления

emulator/console.py

Зачем нужен этот шаг

У Console уже есть метод пошагового выполнения на одну инструкцию

console.step()

Это наименьшая операция машинного времени в этом эмуляторе. Она выполняет одну инструкцию CPU, продвигает PPU на количество циклов CPU * 3, а затем обрабатывает любой отложенный NMI.

Ручным исполнителям и будущим фронтендам обычно нужна более крупная операция

run emulation until one full PPU frame completes
then ask for a framebuffer explicitly

На этом шаге добавляется

console.step_until_next_frame(max_cpu_instructions: int | None = None) -> int

Пример реализации

def step_until_next_frame(
    self,
    max_cpu_instructions: int | None = None,
) -> int:
    start_frame = self.ppu.frame
    executed = 0

    while self.ppu.frame == start_frame:
        if max_cpu_instructions is not None:
            if executed >= max_cpu_instructions:
                raise RuntimeError("Frame did not complete before instruction limit")

        self.step()
        executed += 1

    return executed

Разница между step() и step_until_next_frame():

step()
    executes exactly one CPU instruction
    advances PPU by that instruction's cycles * 3
    returns CPU cycles for that instruction

step_until_next_frame()
    calls step() repeatedly until ppu.frame changes
    returns how many CPU instructions were executed

Пример использования

console.step_until_next_frame()
framebuffer = console.render_background_framebuffer()

Почему max_cpu_instructions необязателен: этот параметр не относится к поведению железа NES. Это защитный механизм эмулятора для отладки/тестирования.

При значении None искусственного ограничения по количеству инструкций нет. Это полезно для реального или ручного выполнения:

console.step_until_next_frame()

При целочисленном значении помощник выбрасывает исключение, если указанное количество инструкций CPU выполнилось без появления нового кадра. Это полезно для тестов и отладки, поскольку предотвращает бесконечные циклы, если CPU завис, опкод отсутствует или кадр никогда не завершается:

console.step_until_next_frame(max_cpu_instructions=10)

Важное разделение

step_until_next_frame()
    advances emulation time

render_background_framebuffer()
    observes current PPU memory and returns Framebuffer data

Не выполняйте рендеринг автоматически внутри step_until_next_frame().

Вне рамок этого шага

отображение pygame
спрайты
OAMDMA
точная задержка NMI
динамические штрафы циклов CPU
ввод с контроллера

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

uv run pytest tests/chapter_05_rendering_pipeline/test_287_console_step_until_next_frame.py -v

Пример реализации

def step_until_next_frame(
    self,
    max_cpu_instructions: int | None = None,
) -> int:
    start_frame = self.ppu.frame
    executed = 0

    while self.ppu.frame == start_frame:
        if max_cpu_instructions is not None:
            if executed >= max_cpu_instructions:
                raise RuntimeError("Frame did not complete before instruction limit")

        self.step()
        executed += 1

    return executed

Показать код тестаtest_287_console_step_until_next_frame.py

import pytest

from emulator.bus.cpu_bus import CpuBus
from emulator.console import Console
from emulator.cpu.cpu import CPU
from emulator.memory.fake_rom import FakeROM
from emulator.ppu.ppu import PPU_CYCLES_PER_SCANLINE, PPU_SCANLINES_PER_FRAME
from tests.helpers import load_program


def make_console_with_nop_rom(program_size: int = 0x8000) -> tuple[Console, CPU, FakeROM]:
    """
    Build a Console with FakeROM filled with NOP instructions.

    NOP is useful here because it is implemented, deterministic, and takes 2 CPU
    cycles. Console.step() will therefore advance the PPU by 6 cycles per
    instruction.
    """
    rom = FakeROM()
    load_program(rom, 0x8000, [0xEA] * program_size)
    bus = CpuBus(program_rom=rom)
    cpu = CPU(bus)
    cpu.pc = 0x8000
    return Console(cpu=cpu, ppu=bus.ppu), cpu, rom


def test_console_exposes_step_until_next_frame_method():
    """
    Objective:
    Console exposes a frame-level stepping helper.
    """
    assert hasattr(Console, "step_until_next_frame")
    assert callable(Console.step_until_next_frame)


def test_step_until_next_frame_advances_ppu_frame_counter():
    """
    Objective:
    The helper repeatedly calls Console.step() until the PPU frame changes.
    """
    console, _cpu, _rom = make_console_with_nop_rom()
    assert console.ppu.frame == 0

    executed = console.step_until_next_frame(max_cpu_instructions=20_000)

    assert executed > 0
    assert console.ppu.frame == 1


def test_step_until_next_frame_returns_instruction_count():
    """
    Objective:
    Returning the executed instruction count gives tests and debug logs useful
    evidence about frame progression.

    With NOP:
        2 CPU cycles * 3 = 6 PPU cycles per instruction
    """
    console, _cpu, _rom = make_console_with_nop_rom()

    executed = console.step_until_next_frame(max_cpu_instructions=20_000)

    ppu_cycles_per_frame = PPU_CYCLES_PER_SCANLINE * PPU_SCANLINES_PER_FRAME

    assert executed > 0
    assert executed * 6 >= ppu_cycles_per_frame


def test_step_until_next_frame_raises_when_instruction_limit_is_too_small():
    """
    Objective:
    The optional max_cpu_instructions limit prevents tests/debug runs from hanging
    forever if a frame never completes.
    """
    console, _cpu, _rom = make_console_with_nop_rom()

    with pytest.raises(RuntimeError, match="Frame did not complete before instruction limit"):
        console.step_until_next_frame(max_cpu_instructions=1)


def test_step_until_next_frame_allows_no_limit_when_argument_is_none():
    """
    Objective:
    max_cpu_instructions=None means no artificial limit. This is useful for manual
    runs or future real-ROM loops.

    The test starts the PPU close to frame completion so it finishes quickly.
    """
    console, _cpu, _rom = make_console_with_nop_rom()

    console.ppu.scanline = PPU_SCANLINES_PER_FRAME - 1
    console.ppu.cycle = PPU_CYCLES_PER_SCANLINE - 6

    executed = console.step_until_next_frame()

    assert executed == 1
    assert console.ppu.frame == 1


def test_step_until_next_frame_does_not_render_automatically():
    """
    Objective:
    Frame stepping advances time only. Rendering remains an explicit separate call.

    This protects the boundary:
        step_until_next_frame() -> timing
        render_background_framebuffer() -> observation/rendering
    """
    console, _cpu, _rom = make_console_with_nop_rom()

    def fail_if_render_called():
        raise AssertionError("step_until_next_frame must not render automatically")

    console.render_background_framebuffer = fail_if_render_called

    console.ppu.scanline = PPU_SCANLINES_PER_FRAME - 1
    console.ppu.cycle = PPU_CYCLES_PER_SCANLINE - 6

    executed = console.step_until_next_frame()

    assert executed == 1
    assert console.ppu.frame == 1

Тестовые функции (6)

test_console_exposes_step_until_next_frame_method
test_step_until_next_frame_advances_ppu_frame_counter
test_step_until_next_frame_returns_instruction_count
test_step_until_next_frame_raises_when_instruction_limit_is_too_small
test_step_until_next_frame_allows_no_limit_when_argument_is_none
test_step_until_next_frame_does_not_render_automatically