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

为什么要给掩码起一个别名？早期课程已经在 Console 内部使用了 ppu_background_to_opaque_mask 这个名字。以该名字导入新的视口掩码函数，可以让整帧渲染路径使用新行为，同时不破坏与那些早期课程的兼容性。

《超级马里奥兄弟》的临时限制：如果它现在还没有按预期滚动，不必担心。此步骤在整帧中只使用一个滚动位置。《超级马里奥兄弟》在同一帧中，固定的状态栏使用一个位置，而移动的游戏区域使用另一个位置。因此，在这个测试通过之后，游戏仍然可能显示静止的背景、移动的状态栏，或其他不正确的滚动效果。这是预期之中的。后续步骤将记录滚动的变化，并把状态栏和游戏区域渲染为独立的水平条带。

范围之外

更改 sprite-zero-hit 调度
追踪 $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