351. De scanlines temporizadas a máscara opaca

Componer una máscara de opacidad de fondo a partir de 240 estados de scanline completados.

Lección 351 de 356 · tests/chapter_13_scrolling/test_351_timed_scanlines_to_opaque_mask.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

Las filas de framebuffer temporizadas pueden mostrar un área de estado fija y un área de juego desplazada de forma distinta en un mismo fotograma. Las decisiones de prioridad de sprites y de sprite-zero-hit también necesitan la opacidad del fondo en esas mismas coordenadas de pantalla exactas. Si los píxeles RGB usan estados temporizados mientras que la opacidad usa una única instantánea final de t, los sprites pueden aparecer delante de tiles sólidos que deberían ocultarlos.

Un BackgroundOpaqueMask es una lista plana de 256x240 valores booleanos

True:  the decoded background pattern pixel is nonzero
False: the decoded background pattern pixel is transparent

La opacidad es información de patrón, no una prueba de color RGB. Un píxel de patrón visible puede usar un color de paleta negro, mientras que un píxel de patrón transparente muestra el color de fondo universal.

El compositor de la máscara debe reflejar exactamente la selección de coordenadas del framebuffer:

state = completed_scanline_scroll_states[screen_y]
logical_x = (viewport_x + screen_x) % 512

logical X 0-255:   read the left source mask
logical X 256-511: read the right source mask after subtracting 256

Para este hito horizontal, la Y de origen sigue siendo screen_y.

¿Por qué cachear máscaras de origen? El viewport X puede cambiar en cada scanline sin que cambie el par de origen lógico.

La caché local construye cada par una sola vez por composición

$2000 key -> masks for ($2000, $2400)
$2800 key -> masks for ($2800, $2C00)

Invariantes importantes

la entrada contiene exactamente 240 estados completados
la salida contiene exactamente 256 * 240 entradas booleanas
el índice de estado, la fila de origen y la fila de destino usan el mismo screen_y
las coordenadas horizontales dan la vuelta a lo largo del par completo de 512 píxeles
cada par lógico se construye como máximo una vez por composición
los cambios de viewport-X reutilizan el par de origen existente
el código de la máscara de opacidad nunca llama al renderizado del framebuffer
las correspondencias de coordenadas del framebuffer y de la máscara de opacidad permanecen idénticas

Concepto erróneo habitual

No derives esta máscara a partir de valores RGB ya renderizados. La prioridad de sprites depende de si el valor original del patrón de fondo era cero, algo que no puede reconstruirse de forma fiable a partir de su color de paleta final.

Estrategia de pruebas

Estas pruebas sustituyen la construcción de máscaras respaldada por la PPU por máscaras sintéticas. Cada valor booleano es una función determinista de la dirección base lógica, la X de origen y la Y de origen. Eso hace observables la selección incorrecta de pares, el indexado incorrecto de filas y los errores de ajuste horizontal sin involucrar la decodificación de CHR, las paletas ni el mirroring del cartucho.

Fuera de alcance

activar este helper en el adaptador público de la máscara de opacidad
selección de reserva para fotogramas de inicio o incompletos
integración con sprite-zero-hit
desplazamiento vertical completo de la fila de origen

Implementación de ejemplo completa (lógica muy similar a _timed_scanlines_to_framebuffer):

# emulator/rendering/ppu_background_renderer.py

# --- NEW BLOCK: COMPOSE COMPLETED TIMED OPACITY ROWS ---
def _timed_scanlines_to_opaque_mask(
    ppu: PPU,
) -> BackgroundOpaqueMask:
    states = ppu.completed_scanline_scroll_states

    if len(states) != NAMETABLE_PIXEL_HEIGHT:
        raise ValueError(
            "Timed opacity mask requires exactly 240 scanline states"
        )

    result: BackgroundOpaqueMask = [False] * (
        NAMETABLE_PIXEL_WIDTH * NAMETABLE_PIXEL_HEIGHT
    )
    pair_cache: dict[
        int,
        tuple[BackgroundOpaqueMask, BackgroundOpaqueMask],
    ] = {}
    logical_width = NAMETABLE_PIXEL_WIDTH * 2

    for screen_y, state in enumerate(states):
        left_base, right_base = _scanline_horizontal_pair(state)

        if left_base not in pair_cache:
            pair_cache[left_base] = (
                ppu_background_to_opaque_mask(
                    ppu,
                    base_nametable_addr=left_base,
                ),
                ppu_background_to_opaque_mask(
                    ppu,
                    base_nametable_addr=right_base,
                ),
            )

        left, right = pair_cache[left_base]
        viewport_x = _scanline_viewport_x(state)
        destination_row = screen_y * NAMETABLE_PIXEL_WIDTH

        for screen_x in range(NAMETABLE_PIXEL_WIDTH):
            logical_x = (viewport_x + screen_x) % logical_width

            if logical_x < NAMETABLE_PIXEL_WIDTH:
                source = left
                source_x = logical_x
            else:
                source = right
                source_x = logical_x - NAMETABLE_PIXEL_WIDTH

            destination_index = destination_row + screen_x
            source_index = destination_row + source_x
            result[destination_index] = source[source_index]

    return result

Ejecutar esta lección

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

Implementación de ejemplo

Un BackgroundOpaqueMask es una lista plana de 256x240 valores booleanos

state = completed_scanline_scroll_states[screen_y]
logical_x = (viewport_x + screen_x) % 512

logical X 0-255:   read the left source mask
logical X 256-511: read the right source mask after subtracting 256

Fuera de alcance

# emulator/rendering/ppu_background_renderer.py

# --- NEW BLOCK: COMPOSE COMPLETED TIMED OPACITY ROWS ---
def _timed_scanlines_to_opaque_mask(
    ppu: PPU,
) -> BackgroundOpaqueMask:
    states = ppu.completed_scanline_scroll_states

    if len(states) != NAMETABLE_PIXEL_HEIGHT:
        raise ValueError(
            "Timed opacity mask requires exactly 240 scanline states"
        )

    result: BackgroundOpaqueMask = [False] * (
        NAMETABLE_PIXEL_WIDTH * NAMETABLE_PIXEL_HEIGHT
    )
    pair_cache: dict[
        int,
        tuple[BackgroundOpaqueMask, BackgroundOpaqueMask],
    ] = {}
    logical_width = NAMETABLE_PIXEL_WIDTH * 2

    for screen_y, state in enumerate(states):
        left_base, right_base = _scanline_horizontal_pair(state)

        if left_base not in pair_cache:
            pair_cache[left_base] = (
                ppu_background_to_opaque_mask(
                    ppu,
                    base_nametable_addr=left_base,
                ),
                ppu_background_to_opaque_mask(
                    ppu,
                    base_nametable_addr=right_base,
                ),
            )

        left, right = pair_cache[left_base]
        viewport_x = _scanline_viewport_x(state)
        destination_row = screen_y * NAMETABLE_PIXEL_WIDTH

        for screen_x in range(NAMETABLE_PIXEL_WIDTH):
            logical_x = (viewport_x + screen_x) % logical_width

            if logical_x < NAMETABLE_PIXEL_WIDTH:
                source = left
                source_x = logical_x
            else:
                source = right
                source_x = logical_x - NAMETABLE_PIXEL_WIDTH

            destination_index = destination_row + screen_x
            source_index = destination_row + source_x
            result[destination_index] = source[source_index]

    return result

Ver código del testtest_351_timed_scanlines_to_opaque_mask.py

from collections import Counter

import pytest

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


SOURCE_PHASES = {
    0x2000: 0,
    0x2400: 1,
    0x2800: 2,
    0x2C00: 3,
}


def make_state(
    viewport_x: int,
    *,
    nametable_y: int = 0,
) -> BackgroundScanlineState:
    """Encode horizontal pixel X and vertical pair selection into one state."""
    nametable_x, pair_x = divmod(viewport_x, NAMETABLE_PIXEL_WIDTH)
    coarse_x, fine_x = divmod(pair_x, 8)
    vram_addr = (
        coarse_x
        | ((nametable_x & 1) << 10)
        | ((nametable_y & 1) << 11)
    )
    return BackgroundScanlineState(vram_addr=vram_addr, fine_x=fine_x)


def source_value(
    base_nametable_addr: int,
    source_x: int,
    source_y: int,
) -> bool:
    """Produce distinguishable Boolean patterns for logical source coordinates."""
    phase = SOURCE_PHASES[base_nametable_addr]
    return (phase + source_x + source_y) % 5 in (0, 1)


def make_source_mask(base_nametable_addr: int) -> list[bool]:
    """Build one synthetic logical nametable mask."""
    return [
        source_value(base_nametable_addr, source_x, source_y)
        for source_y in range(NAMETABLE_PIXEL_HEIGHT)
        for source_x in range(NAMETABLE_PIXEL_WIDTH)
    ]


def install_fake_mask_renderer(monkeypatch):
    """Replace PPU-backed mask construction and return its logical-address call log."""
    calls: list[int] = []

    def fake_renderer(ppu, base_nametable_addr=0x2000):
        calls.append(base_nametable_addr)
        return make_source_mask(base_nametable_addr)

    monkeypatch.setattr(
        ppu_background_renderer,
        "ppu_background_to_opaque_mask",
        fake_renderer,
    )
    return calls


@pytest.mark.parametrize("wrong_length", [0, 1, 239, 241])
def test_timed_mask_compositor_requires_exactly_240_states(wrong_length):
    """
    Objective:
    Reject missing or oversized coordinate evidence instead of producing a partial mask.
    """
    ppu = PPU()
    ppu.completed_scanline_scroll_states = tuple(
        make_state(0)
        for _ in range(wrong_length)
    )

    with pytest.raises(
        ValueError,
        match="exactly 240 scanline states",
    ):
        _timed_scanlines_to_opaque_mask(ppu)


def test_result_contains_one_boolean_for_every_screen_pixel(monkeypatch):
    """
    Objective:
    Preserve the flat mask contract expected by sprite-priority consumers.
    """
    install_fake_mask_renderer(monkeypatch)
    ppu = PPU()
    ppu.completed_scanline_scroll_states = tuple(
        make_state(0)
        for _ in range(NAMETABLE_PIXEL_HEIGHT)
    )

    result = _timed_scanlines_to_opaque_mask(ppu)

    assert len(result) == NAMETABLE_PIXEL_WIDTH * NAMETABLE_PIXEL_HEIGHT
    assert all(isinstance(value, bool) for value in result)


def test_each_mask_row_uses_its_matching_recorded_state(monkeypatch):
    """
    Objective:
    Align opacity with a fixed upper area and a differently scrolled lower area.
    """
    install_fake_mask_renderer(monkeypatch)
    ppu = PPU()
    ppu.completed_scanline_scroll_states = tuple(
        make_state(0 if screen_y < 32 else 40)
        for screen_y in range(NAMETABLE_PIXEL_HEIGHT)
    )

    result = _timed_scanlines_to_opaque_mask(ppu)

    assert result[0 * NAMETABLE_PIXEL_WIDTH] == source_value(0x2000, 0, 0)
    assert result[31 * NAMETABLE_PIXEL_WIDTH] == source_value(0x2000, 0, 31)
    assert result[32 * NAMETABLE_PIXEL_WIDTH] == source_value(0x2000, 40, 32)
    assert result[239 * NAMETABLE_PIXEL_WIDTH] == source_value(0x2000, 40, 239)


def test_mask_selection_wraps_from_right_source_to_left(monkeypatch):
    """
    Objective:
    Match framebuffer wrapping across logical positions 510, 511, then 0.
    """
    install_fake_mask_renderer(monkeypatch)
    ppu = PPU()
    ppu.completed_scanline_scroll_states = tuple(
        make_state(510)
        for _ in range(NAMETABLE_PIXEL_HEIGHT)
    )

    result = _timed_scanlines_to_opaque_mask(ppu)
    row = 17 * NAMETABLE_PIXEL_WIDTH

    assert result[row] == source_value(0x2400, 254, 17)
    assert result[row + 1] == source_value(0x2400, 255, 17)
    assert result[row + 2] == source_value(0x2000, 0, 17)


def test_different_viewport_x_values_reuse_one_mask_pair(monkeypatch):
    """
    Objective:
    Keep per-row pixel selection independent from expensive source-mask construction.
    """
    calls = install_fake_mask_renderer(monkeypatch)
    ppu = PPU()
    ppu.completed_scanline_scroll_states = tuple(
        make_state((screen_y * 3) % 512)
        for screen_y in range(NAMETABLE_PIXEL_HEIGHT)
    )

    _timed_scanlines_to_opaque_mask(ppu)

    assert Counter(calls) == Counter({0x2000: 1, 0x2400: 1})


def test_each_logical_mask_pair_is_built_once_when_both_are_used(monkeypatch):
    """
    Objective:
    Bound source work while preserving vertical logical-pair selection per row.
    """
    calls = install_fake_mask_renderer(monkeypatch)
    ppu = PPU()
    ppu.completed_scanline_scroll_states = tuple(
        make_state(
            viewport_x=0,
            nametable_y=0 if screen_y < 120 else 1,
        )
        for screen_y in range(NAMETABLE_PIXEL_HEIGHT)
    )

    result = _timed_scanlines_to_opaque_mask(ppu)

    assert Counter(calls) == Counter(
        {
            0x2000: 1,
            0x2400: 1,
            0x2800: 1,
            0x2C00: 1,
        }
    )
    assert result[119 * NAMETABLE_PIXEL_WIDTH] == source_value(0x2000, 0, 119)
    assert result[120 * NAMETABLE_PIXEL_WIDTH] == source_value(0x2800, 0, 120)


def test_timed_mask_composition_never_renders_rgb_framebuffers(monkeypatch):
    """
    Objective:
    Keep Boolean opacity production independent from RGB rendering and palette colors.
    """
    install_fake_mask_renderer(monkeypatch)
    ppu = PPU()
    ppu.completed_scanline_scroll_states = tuple(
        make_state(0)
        for _ in range(NAMETABLE_PIXEL_HEIGHT)
    )

    def forbidden_framebuffer_call(*args, **kwargs):
        raise AssertionError("Opacity composition must not render RGB framebuffers")

    monkeypatch.setattr(
        ppu_background_renderer,
        "ppu_background_to_framebuffer",
        forbidden_framebuffer_call,
    )

    result = _timed_scanlines_to_opaque_mask(ppu)

    assert len(result) == NAMETABLE_PIXEL_WIDTH * NAMETABLE_PIXEL_HEIGHT

Funciones de test (7)

test_timed_mask_compositor_requires_exactly_240_states
test_result_contains_one_boolean_for_every_screen_pixel
test_each_mask_row_uses_its_matching_recorded_state
test_mask_selection_wraps_from_right_source_to_left
test_different_viewport_x_values_reuse_one_mask_pair
test_each_logical_mask_pair_is_built_once_when_both_are_used
test_timed_mask_composition_never_renders_rgb_framebuffers