287. Console avanza hasta el siguiente fotograma

Añadir Console.step_until_next_frame() para el avance a nivel de fotograma.

Lección 287 de 356 · tests/chapter_05_rendering_pipeline/test_287_console_step_until_next_frame.py

Archivo a actualizar

emulator/console.py

Por qué existe este paso

Console ya tiene un método de avance de una instrucción

console.step()

Esa es la operación de tiempo de máquina más pequeña de este emulador. Ejecuta una instrucción de CPU, avanza la PPU en ciclos de CPU * 3 y luego consume cualquier NMI pendiente.

Los ejecutores manuales y los futuros frontends normalmente necesitan una operación más grande

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

Este paso añade

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

Ejemplo de implementación

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

Diferencia entre step() y 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

Ejemplo de uso

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

Por qué max_cpu_instructions es opcional: este parámetro no es comportamiento de hardware del NES. Es una salvaguarda de depuración/testing del emulador.

Con None, no hay límite artificial de instrucciones. Esto es útil para la ejecución real o manual:

console.step_until_next_frame()

Con un entero, el ayudante lanza una excepción si se ejecutan esa cantidad de instrucciones de CPU sin que se complete un nuevo fotograma. Esto es útil para tests y depuración porque evita bucles infinitos si la CPU se atasca, falta un opcode o un fotograma nunca se completa:

console.step_until_next_frame(max_cpu_instructions=10)

Separación importante

step_until_next_frame()
    advances emulation time

render_background_framebuffer()
    observes current PPU memory and returns Framebuffer data

No renderices automáticamente dentro de step_until_next_frame().

Fuera de alcance

visualización con pygame
sprites
OAMDMA
latencia exacta de NMI
penalizaciones dinámicas de ciclos de CPU
entrada del mando

Ejecutar esta lección

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

Implementación de ejemplo

Ejemplo de implementación

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

Ver código del testtest_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

Funciones de test (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