336. Console использует область просмотра фона

Интегрировать горизонтальные области просмотра фреймбуфера и маски непрозрачности в Console.

Урок 336 из 356 · tests/chapter_13_scrolling/test_336_console_uses_background_viewport.py

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

emulator/console.py

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

Шаги 334 и 335 формируют данные фона, учитывающие область просмотра, из текущего состояния прокрутки PPU. Этот шаг собирает эти новые функции внутри Console так, чтобы путь полного кадра использовал и фреймбуфер с применённой прокруткой, и соответствующую ему маску непрозрачности.

Что изменяется

Console.render_background_framebuffer()
    -> keeps the older fixed-background behavior

Console.render_framebuffer()
    -> uses ppu_background_viewport_to_framebuffer(self.ppu)
    -> uses the new viewport opacity mask through a compatibility alias
    -> passes both new results to the existing sprite compositor

Зачем для маски используется псевдоним? В предыдущих уроках имя ppu_background_to_opaque_mask уже используется внутри Console. Импорт новой функции маски области просмотра под этим именем позволяет пути полного кадра использовать новое поведение, не нарушая совместимость с теми предыдущими уроками.

Временное ограничение Super Mario Bros.: не беспокойтесь, если прокрутка пока работает не так, как ожидается. Этот шаг использует только одну позицию прокрутки на весь кадр. Super Mario Bros. в течение одного и того же кадра использует одну позицию для фиксированной строки состояния и другую — для движущейся игровой области. Поэтому после прохождения этого теста игра всё ещё может показывать неподвижный фон, движущуюся строку состояния или иную некорректную прокрутку. Это ожидаемо. В будущих шагах изменения прокрутки будут записываться, а строка состояния и игровой процесс будут отрисовываться как отдельные горизонтальные полосы.

Вне объёма работ

изменение планирования попадания нулевого спрайта
трассировка записей в $2005
отрисовка полос при разделённом экране
вертикальная попиксельная прокрутка
pygame

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

# emulator/console.py

from emulator.rendering.ppu_background_renderer import (
    ppu_background_to_framebuffer,
    # --- NEW LINE: FULL-FRAME RENDERING USES THE VIEWPORT ADAPTER ---
    ppu_background_viewport_to_framebuffer,
    # --- UPDATED LINE: USE THE NEW MASK WITH THE EXISTING CONSOLE NAME ---
    ppu_background_viewport_to_opaque_mask as ppu_background_to_opaque_mask,
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
)

...

def render_background_framebuffer(self) -> Framebuffer:
    # Keep the older background-only behavior for compatibility.
    return ppu_background_to_framebuffer(self.ppu)

def render_framebuffer(self) -> Framebuffer:
    # --- UPDATED LINE: FULL-FRAME OUTPUT USES THE VIEWPORT FRAMEBUFFER ---
    background = ppu_background_viewport_to_framebuffer(self.ppu)

    # The existing name now refers to the new viewport-mask function.
    background_opaque_mask = ppu_background_to_opaque_mask(self.ppu)

    ...
    # Everything remains the same below this point.

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

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

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

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

# emulator/console.py

from emulator.rendering.ppu_background_renderer import (
    ppu_background_to_framebuffer,
    # --- NEW LINE: FULL-FRAME RENDERING USES THE VIEWPORT ADAPTER ---
    ppu_background_viewport_to_framebuffer,
    # --- UPDATED LINE: USE THE NEW MASK WITH THE EXISTING CONSOLE NAME ---
    ppu_background_viewport_to_opaque_mask as ppu_background_to_opaque_mask,
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
)

...

def render_background_framebuffer(self) -> Framebuffer:
    # Keep the older background-only behavior for compatibility.
    return ppu_background_to_framebuffer(self.ppu)

def render_framebuffer(self) -> Framebuffer:
    # --- UPDATED LINE: FULL-FRAME OUTPUT USES THE VIEWPORT FRAMEBUFFER ---
    background = ppu_background_viewport_to_framebuffer(self.ppu)

    # The existing name now refers to the new viewport-mask function.
    background_opaque_mask = ppu_background_to_opaque_mask(self.ppu)

    ...
    # Everything remains the same below this point.

Показать код тестаtest_336_console_uses_background_viewport.py

from emulator.bus.cpu_bus import CpuBus
from emulator.console import Console
from emulator.cpu.cpu import CPU
from emulator.memory.fake_rom import FakeROM
from emulator.ppu.ppu import PPU
from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.nametable_renderer import BackgroundOpaqueMask
from emulator.rendering.ppu_background_renderer import (
    ppu_background_to_framebuffer as one_nametable_to_framebuffer,
    ppu_background_to_opaque_mask as one_nametable_to_opaque_mask,
    ppu_background_viewport_to_framebuffer,
    ppu_background_viewport_to_opaque_mask,
)


def make_console() -> Console:
    """Build a Console whose CPU and renderer observe the same PPU instance."""
    cpu_bus = CpuBus(program_rom=FakeROM())
    cpu = CPU(cpu_bus)
    return Console(cpu=cpu, ppu=cpu_bus.ppu)


def test_console_preserves_fixed_background_api_and_aliases_viewport_mask():
    """
    Objective:
    Keep the old background-only behavior and connect the existing mask name to the
    new viewport-mask behavior.
    """
    import emulator.console as console_module

    assert (
        console_module.ppu_background_to_framebuffer
        is one_nametable_to_framebuffer
    )
    assert (
        console_module.ppu_background_viewport_to_framebuffer
        is ppu_background_viewport_to_framebuffer
    )
    assert (
        console_module.ppu_background_to_opaque_mask
        is ppu_background_viewport_to_opaque_mask
    )


def test_console_passes_matching_viewport_framebuffer_and_mask_to_sprite_compositor(
    monkeypatch,
):
    """
    Objective:
    The displayed background and sprite-priority mask must come from viewport-aware
    adapters and reach the existing compositor unchanged.
    """
    import emulator.console as console_module

    console = make_console()
    expected_background = Framebuffer()
    expected_mask: BackgroundOpaqueMask = [False] * (256 * 240)
    expected_result = Framebuffer()
    captured = {}

    def fake_viewport_framebuffer(ppu: PPU) -> Framebuffer:
        captured["framebuffer_ppu"] = ppu
        return expected_background

    def fake_viewport_mask(ppu: PPU) -> BackgroundOpaqueMask:
        captured["mask_ppu"] = ppu
        return expected_mask

    def fake_compositor(**kwargs):
        captured["compositor"] = kwargs
        return expected_result

    monkeypatch.setattr(
        console_module,
        "ppu_background_viewport_to_framebuffer",
        fake_viewport_framebuffer,
    )
    monkeypatch.setattr(
        console_module,
        "ppu_background_to_opaque_mask",
        fake_viewport_mask,
    )
    monkeypatch.setattr(
        console_module,
        "composite_background_and_sprites",
        fake_compositor,
    )

    result = console.render_framebuffer()

    assert captured["framebuffer_ppu"] is console.ppu
    assert captured["mask_ppu"] is console.ppu
    assert captured["compositor"]["background"] is expected_background
    assert captured["compositor"]["background_opaque_mask"] is expected_mask
    assert captured["compositor"]["oam"] is console.ppu.oam
    assert result is expected_result


def test_renderer_module_keeps_old_one_nametable_functions_distinct():
    """
    Objective:
    Adding Console aliases must not replace the older renderer functions.
    """
    assert one_nametable_to_framebuffer is not ppu_background_viewport_to_framebuffer
    assert one_nametable_to_opaque_mask is not ppu_background_viewport_to_opaque_mask

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

test_console_preserves_fixed_background_api_and_aliases_viewport_mask
test_console_passes_matching_viewport_framebuffer_and_mask_to_sprite_compositor
test_renderer_module_keeps_old_one_nametable_functions_distinct