349. Синхронизированные scanlines в framebuffer

Составить один framebuffer из 240 завершённых синхронизированных состояний scanline.

Урок 349 из 356 · tests/chapter_13_scrolling/test_349_timed_scanlines_to_framebuffer.py

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

emulator/rendering/ppu_background_renderer.py

Ссылки

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

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

Завершённый кадр может содержать разную горизонтальную позицию viewport для каждой видимой строки. Один снимок t конца кадра не может представить как фиксированную область статуса, так и движущуюся область геймплея, поэтому высокоуровневый рендерер должен составить каждую строку из соответствующего BackgroundScanlineState.

Для каждой строки назначения

state = completed_scanline_scroll_states[screen_y]
left_base, right_base = logical pair selected by state
viewport_x = horizontal pixel position decoded from state

Для каждого пикселя назначения

logical_x = (viewport_x + screen_x) % 512

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

Исходная строка остаётся screen_y для этого горизонтального этапа. Полный выбор вертикальной исходной строки — это отдельная будущая работа.

Почему кэшировать исходные пары? Строки могут иметь разные значения viewport X при чтении одних и тех же двух nametable. Рендеринг обеих полных исходных nametable снова для каждой строки выполнил бы столько же, сколько 480 исходных рендеров. Локальный словарь вместо этого хранит каждую логическую пару один раз для этой композиции:

$2000 key -> rendered ($2000, $2400) pair
$2800 key -> rendered ($2800, $2C00) pair

Кэш намеренно локален. Данные nametable, pattern, attribute или palette могут измениться перед более поздним кадром, поэтому кэширование между кадрами потребует явных и подверженных ошибкам правил инвалидации.

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

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

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

Не вызывайте существующий полнокадровый горизонтальный композитор viewport один раз за строку. Это построит 240 временных framebuffer 256x240 для сохранения только одной строки из каждого. Эта вспомогательная функция записывает каждую строку назначения непосредственно в один результирующий framebuffer.

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

Эти тесты заменяют рендеринг nametable синтетическими исходными framebuffer, чьи кортежи RGB кодируют логическую базу, исходный X и исходный Y. Это изолирует механику композиции строк от декодирования pattern, выбора palette, памяти PPU и зеркалирования.

Вне области действия

изменение публичного адаптера viewport
поведение fallback для недоступного синхронизированного кадра
композиция opacity-mask
полная вертикальная прокрутка исходной строки
постоянные кэши рендеринга

Полный пример реализации

# emulator/rendering/ppu_background_renderer.py

# --- UPDATED LINES: IMPORT FRAMEBUFFER DIMENSIONS ---
from emulator.rendering.background_viewport import (
    NAMETABLE_PIXEL_HEIGHT,
    NAMETABLE_PIXEL_WIDTH,
    ...
)

# --- NEW BLOCK: COMPOSE COMPLETED TIMED SCANLINES ---
def _timed_scanlines_to_framebuffer(ppu: PPU) -> Framebuffer:
    states = ppu.completed_scanline_scroll_states

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

    result = Framebuffer(
        width=NAMETABLE_PIXEL_WIDTH,
        height=NAMETABLE_PIXEL_HEIGHT,
    )
    pair_cache: dict[int, tuple[Framebuffer, Framebuffer]] = {}
    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_framebuffer(
                    ppu,
                    base_nametable_addr=left_base,
                ),
                ppu_background_to_framebuffer(
                    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.pixels[destination_index] = source.pixels[source_index]

    return result

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

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

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

Для каждой строки назначения

state = completed_scanline_scroll_states[screen_y]
left_base, right_base = logical pair selected by state
viewport_x = horizontal pixel position decoded from state

Для каждого пикселя назначения

logical_x = (viewport_x + screen_x) % 512

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

Полный пример реализации

# emulator/rendering/ppu_background_renderer.py

# --- UPDATED LINES: IMPORT FRAMEBUFFER DIMENSIONS ---
from emulator.rendering.background_viewport import (
    NAMETABLE_PIXEL_HEIGHT,
    NAMETABLE_PIXEL_WIDTH,
    ...
)

# --- NEW BLOCK: COMPOSE COMPLETED TIMED SCANLINES ---
def _timed_scanlines_to_framebuffer(ppu: PPU) -> Framebuffer:
    states = ppu.completed_scanline_scroll_states

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

    result = Framebuffer(
        width=NAMETABLE_PIXEL_WIDTH,
        height=NAMETABLE_PIXEL_HEIGHT,
    )
    pair_cache: dict[int, tuple[Framebuffer, Framebuffer]] = {}
    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_framebuffer(
                    ppu,
                    base_nametable_addr=left_base,
                ),
                ppu_background_to_framebuffer(
                    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.pixels[destination_index] = source.pixels[source_index]

    return result

Показать код тестаtest_349_timed_scanlines_to_framebuffer.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.framebuffer import BLACK, Framebuffer
from emulator.rendering import ppu_background_renderer
from emulator.rendering.ppu_background_renderer import (
    _timed_scanlines_to_framebuffer,
)


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


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 make_source_framebuffer(base_nametable_addr: int) -> Framebuffer:
    """Encode source base, X, and Y in every synthetic RGB pixel."""
    tag = SOURCE_TAGS[base_nametable_addr]
    pixels = [
        (tag, source_x, source_y)
        for source_y in range(NAMETABLE_PIXEL_HEIGHT)
        for source_x in range(NAMETABLE_PIXEL_WIDTH)
    ]
    return Framebuffer(
        width=NAMETABLE_PIXEL_WIDTH,
        height=NAMETABLE_PIXEL_HEIGHT,
        pixels=pixels,
    )


def install_fake_source_renderer(monkeypatch):
    """Return a call log while replacing PPU memory rendering with pure test data."""
    calls: list[int] = []

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

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


@pytest.mark.parametrize("wrong_length", [0, 1, 239, 241])
def test_timed_compositor_requires_exactly_240_states(wrong_length):
    """
    Objective:
    Fail explicitly instead of returning a silently partial or oversized framebuffer.
    """
    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_framebuffer(ppu)


def test_result_has_nes_dimensions_and_populates_every_pixel(monkeypatch):
    """
    Objective:
    Produce one complete framebuffer rather than sparse row fragments.
    """
    install_fake_source_renderer(monkeypatch)
    ppu = PPU()
    ppu.completed_scanline_scroll_states = tuple(
        make_state(0)
        for _ in range(NAMETABLE_PIXEL_HEIGHT)
    )

    result = _timed_scanlines_to_framebuffer(ppu)

    assert result.width == NAMETABLE_PIXEL_WIDTH
    assert result.height == NAMETABLE_PIXEL_HEIGHT
    assert len(result.pixels) == NAMETABLE_PIXEL_WIDTH * NAMETABLE_PIXEL_HEIGHT
    assert all(pixel != BLACK for pixel in result.pixels)


def test_each_output_row_uses_its_matching_recorded_state(monkeypatch):
    """
    Objective:
    Allow a fixed upper region and differently scrolled lower region in one frame.
    """
    install_fake_source_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_framebuffer(ppu)

    assert result.get_pixel(0, 0) == (1, 0, 0)
    assert result.get_pixel(0, 31) == (1, 0, 31)
    assert result.get_pixel(0, 32) == (1, 40, 32)
    assert result.get_pixel(0, 239) == (1, 40, 239)


def test_horizontal_selection_wraps_from_right_source_to_left(monkeypatch):
    """
    Objective:
    Wrap logical positions 510, 511, then 0 across the pair boundary.
    """
    install_fake_source_renderer(monkeypatch)
    ppu = PPU()
    ppu.completed_scanline_scroll_states = tuple(
        make_state(510)
        for _ in range(NAMETABLE_PIXEL_HEIGHT)
    )

    result = _timed_scanlines_to_framebuffer(ppu)

    assert result.get_pixel(0, 17) == (2, 254, 17)
    assert result.get_pixel(1, 17) == (2, 255, 17)
    assert result.get_pixel(2, 17) == (1, 0, 17)


def test_different_viewport_x_values_reuse_one_source_pair(monkeypatch):
    """
    Objective:
    Cache source images independently from each row's pixel-selection offset.
    """
    calls = install_fake_source_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_framebuffer(ppu)

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


def test_each_logical_pair_is_rendered_once_when_both_are_used(monkeypatch):
    """
    Objective:
    Bound source rendering to the two possible horizontal pairs in one composition.
    """
    calls = install_fake_source_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_framebuffer(ppu)

    assert Counter(calls) == Counter(
        {
            0x2000: 1,
            0x2400: 1,
            0x2800: 1,
            0x2C00: 1,
        }
    )
    assert result.get_pixel(0, 119) == (1, 0, 119)
    assert result.get_pixel(0, 120) == (3, 0, 120)

Тестовые функции (6)

test_timed_compositor_requires_exactly_240_states
test_result_has_nes_dimensions_and_populates_every_pixel
test_each_output_row_uses_its_matching_recorded_state
test_horizontal_selection_wraps_from_right_source_to_left
test_different_viewport_x_values_reuse_one_source_pair
test_each_logical_pair_is_rendered_once_when_both_are_used