350. Seleccionar la ruta de framebuffer temporizado

Seleccionar la composición de framebuffer temporizado solo cuando hay un frame completo disponible.

Lección 350 de 356 · tests/chapter_13_scrolling/test_350_select_timed_framebuffer_path.py

Archivo a actualizar

emulator/rendering/ppu_background_renderer.py

Referencias

https://www.nesdev.org/wiki/PPU_rendering
https://www.nesdev.org/wiki/PPU_scrolling

Por qué existe este paso

El compositor temporizado privado requiere un BackgroundScanlineState para cada fila visible. Esa evidencia no está disponible durante el arranque y puede faltar tras un frame incompleto, así que el adaptador público necesita un límite de compatibilidad explícito:

exactly 240 completed states -> use timed row composition
any other tuple length       -> use the existing t + fine-X snapshot path

¿Por qué exigir una longitud exacta en lugar de simplemente comprobar si es verdadero? Una tupla vacía es falsa, pero una tupla parcial de una entrada o de 239 entradas es verdadera. Los datos de temporización parciales todavía dejan filas desconocidas y no deben entrar en un compositor que requiere los 240 estados. La invariante estructural, no si la tupla no está vacía, decide qué mecanismo es seguro.

¿Por qué conservar la ruta antigua? Una PPU nueva no tiene ningún frame completado. Los llamadores históricos y el renderizado de arranque ya tienen un comportamiento determinista basado en temp_vram_addr más fine_x. Mantener ese cuerpo sin cambios proporciona un respaldo seguro hasta que se publique el primer frame temporizado completo.

Flujo de control

ppu_background_viewport_to_framebuffer(ppu)
                     |
                     v
         completed length == 240?
                /                               yes              no
               |                |
               v                v
      timed row helper    existing snapshot path
               |                |
               +------ return --+

Invariantes importantes

exactamente 240 entradas seleccionan el auxiliar temporizado
la composición temporizada retorna de inmediato
el renderizador de origen antiguo y el compositor de frame completo no se ejecutan también
las tuplas vacías, parciales o con exceso de entradas seleccionan el respaldo establecido
el respaldo sigue decodificando ppu.temp_vram_addr y ppu.fine_x
la selección de la máscara de opacidad permanece sin cambios en esta lección

Concepto erróneo común

No captures el ValueError del auxiliar temporizado ni reintentes el respaldo de forma silenciosa. La puerta pública posee la disponibilidad esperada; un error después de la puerta de frame completo indica una invariante rota que debe seguir siendo visible durante la depuración.

Fuera de alcance

la composición temporizada de la máscara de opacidad
la corrección de prioridad sprite/fondo
la integración de la máscara de sprite-zero-hit
el desplazamiento vertical completo de la fila de origen

Implementación de ejemplo completa

# emulator/rendering/ppu_background_renderer.py

def ppu_background_viewport_to_framebuffer(ppu: PPU) -> Framebuffer:
    # --- NEW BLOCK: USE TIMED DATA ONLY WHEN THE FRAME IS COMPLETE ---
    if (
        len(ppu.completed_scanline_scroll_states)
        == NAMETABLE_PIXEL_HEIGHT
    ):
        return _timed_scanlines_to_framebuffer(ppu)

    # Existing temp_vram_addr + fine_x fallback remains unchanged below.
    viewport_x, _ = decode_background_viewport_position(
        temp_vram_addr=ppu.temp_vram_addr,
        fine_x=ppu.fine_x,
    )
    ...

Punto de control manual tras esta lección

Con tu propia ROM legal de Super Mario Bros., ahora puedes jugar lo suficiente para intentar atrapar un champiñón mientras observas el fondo horizontal temporizado. En este hito exacto, el champiñón puede aparecer delante de un tile de fondo sólido que debería ocluirlo visualmente. Ese síntoma es esperado: las filas del framebuffer RGB ahora usan estados de scanline temporizados, pero la máscara de opacidad de fondo usada para la prioridad de sprites todavía usa una única instantánea antigua a nivel de frame. La siguiente lección compondrá las filas de la máscara de opacidad a partir de los mismos estados temporizados para que las decisiones de color y de prioridad usen coordenadas de pantalla idénticas.

Ejecutar esta lección

uv run pytest tests/chapter_13_scrolling/test_350_select_timed_framebuffer_path.py -v

# emulator/rendering/ppu_background_renderer.py def ppu_background_viewport_to_framebuffer(ppu: PPU) -> Framebuffer: # --- NEW BLOCK: USE TIMED DATA ONLY WHEN THE FRAME IS COMPLETE --- if ( len(ppu.completed_scanline_scroll_states) == NAMETABLE_PIXEL_HEIGHT ): return _timed_scanlines_to_framebuffer(ppu) # Existing temp_vram_addr + fine_x fallback remains unchanged below. viewport_x, _ = decode_background_viewport_position( temp_vram_addr=ppu.temp_vram_addr, fine_x=ppu.fine_x, ) ...

import pytest from emulator.ppu.ppu import BackgroundScanlineState, PPU from emulator.rendering.background_viewport import NAMETABLE_PIXEL_HEIGHT from emulator.rendering.framebuffer import Framebuffer from emulator.rendering import ppu_background_renderer from emulator.rendering.ppu_background_renderer import ( ppu_background_viewport_to_framebuffer, ) def make_states(length: int) -> tuple[BackgroundScanlineState, ...]: """Create a tuple whose length controls only public path selection.""" state = BackgroundScanlineState(vram_addr=0, fine_x=0) return (state,) * length def forbidden_fallback_call(*args, **kwargs): """Fail if the complete timed branch continues into old snapshot work.""" raise AssertionError("Complete timed frame must not execute snapshot fallback") def test_exactly_240_states_return_timed_framebuffer_without_fallback(monkeypatch): """ Objective: Activate the new renderer at its exact structural boundary and return its result. """ ppu = PPU() ppu.completed_scanline_scroll_states = make_states( NAMETABLE_PIXEL_HEIGHT ) expected = Framebuffer() timed_calls: list[PPU] = [] def fake_timed_compositor(ppu_argument): timed_calls.append(ppu_argument) return expected monkeypatch.setattr( ppu_background_renderer, "_timed_scanlines_to_framebuffer", fake_timed_compositor, ) monkeypatch.setattr( ppu_background_renderer, "decode_background_viewport_position", forbidden_fallback_call, ) monkeypatch.setattr( ppu_background_renderer, "ppu_background_to_framebuffer", forbidden_fallback_call, ) monkeypatch.setattr( ppu_background_renderer, "compose_horizontal_framebuffer_viewport", forbidden_fallback_call, ) result = ppu_background_viewport_to_framebuffer(ppu) assert result is expected assert timed_calls == [ppu] @pytest.mark.parametrize("noncomplete_length", [0, 1, 239, 241]) def test_noncomplete_tuples_use_existing_snapshot_fallback( monkeypatch, noncomplete_length, ): """ Objective: Preserve deterministic startup and incomplete-frame behavior without guessing rows. """ ppu = PPU() ppu.completed_scanline_scroll_states = make_states(noncomplete_length) ppu.temp_vram_addr = (1 << 11) | 5 ppu.fine_x = 3 expected = Framebuffer() source = Framebuffer() rendered_bases: list[int] = [] decoded_arguments: list[tuple[int, int]] = [] composed_viewports: list[int] = [] def forbidden_timed_call(*args, **kwargs): raise AssertionError("Incomplete frame must not use timed composition") def fake_decode(*, temp_vram_addr, fine_x): decoded_arguments.append((temp_vram_addr, fine_x)) return 43, 0 def fake_render_one(ppu_argument, base_nametable_addr): assert ppu_argument is ppu rendered_bases.append(base_nametable_addr) return source def fake_compose(*, left, right, viewport_x): assert left is source assert right is source composed_viewports.append(viewport_x) return expected monkeypatch.setattr( ppu_background_renderer, "_timed_scanlines_to_framebuffer", forbidden_timed_call, ) monkeypatch.setattr( ppu_background_renderer, "decode_background_viewport_position", fake_decode, ) monkeypatch.setattr( ppu_background_renderer, "ppu_background_to_framebuffer", fake_render_one, ) monkeypatch.setattr( ppu_background_renderer, "compose_horizontal_framebuffer_viewport", fake_compose, ) result = ppu_background_viewport_to_framebuffer(ppu) assert result is expected assert decoded_arguments == [(ppu.temp_vram_addr, ppu.fine_x)] assert rendered_bases == [0x2800, 0x2C00] assert composed_viewports == [43]