351. Тайминговые строки развёртки в маску непрозрачности

Составить одну маску непрозрачности фона из 240 завершённых состояний строк развёртки.

Урок 351 из 356 · tests/chapter_13_scrolling/test_351_timed_scanlines_to_opaque_mask.py

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

emulator/rendering/ppu_background_renderer.py

Ссылки

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

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

Тайминговые строки кадрового буфера позволяют отображать фиксированную область статуса и область геймплея с другой прокруткой в одном кадре. Решения о приоритете спрайтов и попадании sprite-zero также требуют непрозрачности фона в тех же самых экранных координатах. Если RGB-пиксели используют тайминговые состояния, а непрозрачность — один финальный снимок t, спрайты могут оказаться перед сплошными тайлами, которые должны их перекрывать.

`BackgroundOpaqueMask` — это плоский список из 256×240 булевых значений

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

Непрозрачность определяется данными паттерна, а не проверкой RGB-цвета. Видимый пиксель паттерна может использовать чёрный цвет палитры, тогда как прозрачный пиксель паттерна отображает универсальный цвет фона.

Композитор маски должен в точности повторять выбор координат кадрового буфера:

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

Для этого горизонтального этапа исходный Y остаётся равным screen_y.

Зачем кэшировать исходные маски? Viewport X может меняться на каждой строке развёртки, не изменяя логическую исходную пару.

Локальный кэш строит каждую пару один раз за композицию

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

Важные инварианты

вход содержит ровно 240 завершённых состояний
выход содержит ровно 256 * 240 булевых записей
индекс состояния, исходная строка и строка назначения используют один и тот же screen_y
горизонтальные координаты оборачиваются по всей 512-пиксельной паре
каждая логическая пара строится не более одного раза за композицию
изменения viewport-X переиспользуют существующую исходную пару
код маски непрозрачности никогда не вызывает отрисовку кадрового буфера
отображения координат кадрового буфера и маски непрозрачности остаются идентичными

Распространённое заблуждение

Не выводите эту маску из отрендеренных RGB-значений. Приоритет спрайтов зависит от того, было ли исходное значение паттерна фона нулевым, что невозможно надёжно восстановить из итогового цвета палитры.

Стратегия тестирования

Эти тесты заменяют построение масок через PPU синтетическими масками. Каждое булево значение — детерминированная функция логического базового адреса, исходного X и исходного Y. Это делает неправильный выбор пары, неверную индексацию строки и ошибки горизонтального оборачивания наблюдаемыми без привлечения декодирования CHR, палитр или зеркалирования картриджа.

За рамками этого шага

активация этого хелпера в публичном адаптере маски непрозрачности
выбор запасного варианта для запуска или неполных кадров
интеграция sprite-zero-hit
полная вертикальная прокрутка исходной строки

Полный пример реализации (логика очень похожа на _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

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

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

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

`BackgroundOpaqueMask` — это плоский список из 256×240 булевых значений

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

За рамками этого шага

# 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

Показать код тестаtest_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

Тестовые функции (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