352. Seleccionar la ruta de máscara opaca temporizada

Seleccionar la composición de máscara de opacidad temporizada solo cuando hay un fotograma completo disponible.

Lección 352 de 356 · tests/chapter_13_scrolling/test_352_select_timed_opaque_mask_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 paso 351 construyó el mecanismo para componer filas booleanas de opacidad de fondo a partir de los mismos estados temporizados que las filas RGB del framebuffer. El adaptador público de la máscara debe activar ahora ese mecanismo sin romper el comportamiento de inicio ni el de fotogramas incompletos.

Límite de selección

exactly 240 completed states -> timed opacity-mask composition
any other tuple length       -> existing t + fine-X snapshot fallback

Esta compuerta exacta coincide con la del adaptador del framebuffer. Una comprobación de veracidad no es suficiente porque una tupla parcial de una o de 239 entradas no está vacía pero no puede describir todas las filas visibles.

¿Por qué mantener la reserva? Una PPU nueva empieza con una tupla completada vacía. La ruta de instantánea ya establecida sigue siendo un mecanismo de compatibilidad determinista hasta que se publique el primer fotograma temporizado completo. También contiene el límite de pares lógicos y de mirroring previamente probado.

Flujo de control

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

Invariantes importantes

exactamente 240 entradas seleccionan el helper temporizado
la rama temporizada retorna inmediatamente
la construcción de máscara de origen antigua y la composición de fotograma completo no se ejecutan también
tuplas vacías, parciales o sobredimensionadas seleccionan la reserva antigua
la reserva sigue leyendo ppu.temp_vram_addr y ppu.fine_x
la ruta del framebuffer y el código de sprite-zero-hit permanecen sin cambios

Concepto erróneo habitual

No captures errores del helper temporizado ni reintentes silenciosamente la reserva. La compuerta gestiona la disponibilidad de datos esperada. Una vez que un fotograma completo selecciona el helper temporizado, una excepción representa un invariante violado que debe permanecer observable.

¿Qué cambia en la práctica? Console ya usa esta máscara consciente del viewport para la composición de sprites y fondo. El RGB y la prioridad visual de sprites ahora pueden usar coordenadas temporizadas idénticas, corrigiendo casos como una seta apareciendo incorrectamente delante de un tile opaco. El helper independiente de sprite-zero-hit sigue usando su dependencia de máscara más antigua y se alineará en una lección posterior.

Fuera de alcance

cambiar la composición de filas temporizadas
cambiar la compuerta del framebuffer
cambiar el consumo de máscara de sprite-zero-hit
desplazamiento vertical completo de la fila de origen

Implementación de ejemplo completa

# emulator/rendering/ppu_background_renderer.py

def ppu_background_viewport_to_opaque_mask(
    ppu: PPU,
) -> BackgroundOpaqueMask:
    # --- NEW BLOCK: USE TIMED DATA ONLY FOR A COMPLETE FRAME ---
    if (
        len(ppu.completed_scanline_scroll_states)
        == NAMETABLE_PIXEL_HEIGHT
    ):
        return _timed_scanlines_to_opaque_mask(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,
    )
    ...

Ejecutar esta lección

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

Implementación de ejemplo

Implementación de ejemplo completa

# emulator/rendering/ppu_background_renderer.py

def ppu_background_viewport_to_opaque_mask(
    ppu: PPU,
) -> BackgroundOpaqueMask:
    # --- NEW BLOCK: USE TIMED DATA ONLY FOR A COMPLETE FRAME ---
    if (
        len(ppu.completed_scanline_scroll_states)
        == NAMETABLE_PIXEL_HEIGHT
    ):
        return _timed_scanlines_to_opaque_mask(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,
    )
    ...

Ver código del testtest_352_select_timed_opaque_mask_path.py

import pytest


from emulator.ppu.ppu import BackgroundScanlineState, PPU
from emulator.rendering.background_viewport import NAMETABLE_PIXEL_HEIGHT
from emulator.rendering import ppu_background_renderer
from emulator.rendering.ppu_background_renderer import (
    ppu_background_viewport_to_opaque_mask,
)


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 complete timed selection continues into old snapshot work."""
    raise AssertionError("Complete timed mask must not execute snapshot fallback")


def test_exactly_240_states_return_timed_mask_without_fallback(monkeypatch):
    """
    Objective:
    Activate the timed mask at its exact boundary and return its list unchanged.
    """
    ppu = PPU()
    ppu.completed_scanline_scroll_states = make_states(
        NAMETABLE_PIXEL_HEIGHT
    )
    expected = [True, False, True]
    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_opaque_mask",
        fake_timed_compositor,
    )
    monkeypatch.setattr(
        ppu_background_renderer,
        "decode_background_viewport_position",
        forbidden_fallback_call,
    )
    monkeypatch.setattr(
        ppu_background_renderer,
        "ppu_background_to_opaque_mask",
        forbidden_fallback_call,
    )
    monkeypatch.setattr(
        ppu_background_renderer,
        "compose_horizontal_opaque_mask_viewport",
        forbidden_fallback_call,
    )

    result = ppu_background_viewport_to_opaque_mask(ppu)

    assert result is expected
    assert timed_calls == [ppu]


@pytest.mark.parametrize("noncomplete_length", [0, 1, 239, 241])
def test_noncomplete_tuples_use_existing_mask_fallback(
    monkeypatch,
    noncomplete_length,
):
    """
    Objective:
    Preserve deterministic startup and incomplete-frame mask behavior.
    """
    ppu = PPU()
    ppu.completed_scanline_scroll_states = make_states(noncomplete_length)
    ppu.temp_vram_addr = (1 << 11) | 5
    ppu.fine_x = 3

    expected = [True, False]
    source = [False, True]
    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 mask composition")

    def fake_decode(*, temp_vram_addr, fine_x):
        decoded_arguments.append((temp_vram_addr, fine_x))
        return 43, 0


    def fake_build_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_opaque_mask",
        forbidden_timed_call,
    )
    monkeypatch.setattr(
        ppu_background_renderer,
        "decode_background_viewport_position",
        fake_decode,
    )
    monkeypatch.setattr(
        ppu_background_renderer,
        "ppu_background_to_opaque_mask",
        fake_build_one,
    )
    monkeypatch.setattr(
        ppu_background_renderer,
        "compose_horizontal_opaque_mask_viewport",
        fake_compose,
    )

    result = ppu_background_viewport_to_opaque_mask(ppu)

    assert result is expected
    assert decoded_arguments == [(ppu.temp_vram_addr, ppu.fine_x)]
    assert rendered_bases == [0x2800, 0x2C00]
    assert composed_viewports == [43]

Funciones de test (2)

test_exactly_240_states_return_timed_mask_without_fallback
test_noncomplete_tuples_use_existing_mask_fallback