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-hit 判定同样需要在这些确切的屏幕坐标上得到背景不透明度信息。如果 RGB 像素使用的是定时状态,而不透明度却使用单一的最终 t 快照,精灵就可能出现在本应遮挡它们的实心图块前面。

BackgroundOpaqueMask 是一个扁平的 256x240 布尔值列表

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。

为什么要缓存源掩码?视口 X 可能在每条扫描线上都发生变化,而不改变逻辑源对。

本地缓存在每次合成中最多构建每一对一次

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

重要不变量

输入恰好包含 240 个已完成状态
输出恰好包含 256 * 240 个布尔条目
状态索引、源行和目标行使用相同的 screen_y
水平坐标在完整的 512 像素对范围内环绕
每个逻辑对在一次合成中最多构建一次
视口 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 是一个扁平的 256x240 布尔值列表

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