331. 组合水平不透明度掩码视口

从两个相邻的名称表掩码组合出一个已滚动的不透明度掩码。

第 331 / 356 · tests/chapter_13_scrolling/test_331_compose_horizontal_opaque_mask_viewport.py

待更新文件

emulator/rendering/background_viewport.py

参考文档

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

现有流程

build_background_opaque_mask() converts one nametable into a 256x240 list[bool].
Sprite priority and sprite-zero-hit detection index that mask using screen
coordinates.

新行为

This step does not replace the existing mask builder. It composes two already
constructed masks into the same horizontal viewport introduced for framebuffers
in Step 330.

坐标模型

left mask:  logical X   0-255
right mask: logical X 256-511

logical X = (viewport X + screen X) modulo 512

对于视口 X 200

screen X   0-55  <- left X 200-255
screen X  56-255 <- right X   0-199

不变量

每个源都恰好包含 256 * 240 个布尔条目
结果是一个新的 256 * 240 条目列表
源掩码保持不变
Y 行不移动
掩码映射与帧缓冲区映射完全一致

常见误解

该掩码并不是从最终的 RGB 颜色推导不透明度的。它保留的是原始背景图案颜色索引是否非零。

范围之外

从 CHR 或名称表字节构建掩码
读取 PPU 内存
与 Console 集成
与 sprite-zero-hit 集成
垂直滚动
pygame

完整示例实现

# emulator/rendering/background_viewport.py

from emulator.rendering.nametable_renderer import BackgroundOpaqueMask


def compose_horizontal_opaque_mask_viewport(
    left: BackgroundOpaqueMask,
    right: BackgroundOpaqueMask,
    viewport_x: int,
) -> BackgroundOpaqueMask:
    expected_size = NAMETABLE_PIXEL_WIDTH * NAMETABLE_PIXEL_HEIGHT

    if len(left) != expected_size:
        raise ValueError(
            f"Left background opacity mask must contain {expected_size} entries"
        )

    if len(right) != expected_size:
        raise ValueError(
            f"Right background opacity mask must contain {expected_size} entries"
        )

    logical_width = NAMETABLE_PIXEL_WIDTH * 2
    result = [False] * expected_size

    for screen_y in range(NAMETABLE_PIXEL_HEIGHT):
        row_start = 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 = row_start + screen_x
            source_index = row_start + source_x
            result[destination_index] = source[source_index]

    return result

运行本课

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

示例实现

完整示例实现

# emulator/rendering/background_viewport.py

from emulator.rendering.nametable_renderer import BackgroundOpaqueMask


def compose_horizontal_opaque_mask_viewport(
    left: BackgroundOpaqueMask,
    right: BackgroundOpaqueMask,
    viewport_x: int,
) -> BackgroundOpaqueMask:
    expected_size = NAMETABLE_PIXEL_WIDTH * NAMETABLE_PIXEL_HEIGHT

    if len(left) != expected_size:
        raise ValueError(
            f"Left background opacity mask must contain {expected_size} entries"
        )

    if len(right) != expected_size:
        raise ValueError(
            f"Right background opacity mask must contain {expected_size} entries"
        )

    logical_width = NAMETABLE_PIXEL_WIDTH * 2
    result = [False] * expected_size

    for screen_y in range(NAMETABLE_PIXEL_HEIGHT):
        row_start = 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 = row_start + screen_x
            source_index = row_start + source_x
            result[destination_index] = source[source_index]

    return result

查看测试代码test_331_compose_horizontal_opaque_mask_viewport.py

import pytest

from emulator.rendering.background_viewport import (
    NAMETABLE_PIXEL_HEIGHT,
    NAMETABLE_PIXEL_WIDTH,
    compose_horizontal_framebuffer_viewport,
    compose_horizontal_opaque_mask_viewport,
)
from emulator.rendering.framebuffer import BLACK, Framebuffer, RGBColor
from emulator.rendering.nametable_renderer import BackgroundOpaqueMask


MASK_SIZE = NAMETABLE_PIXEL_WIDTH * NAMETABLE_PIXEL_HEIGHT
OPAQUE_COLOR: RGBColor = (255, 255, 255)


def patterned_mask(offset: int) -> BackgroundOpaqueMask:
    """Create row- and column-sensitive Boolean data for mapping tests."""
    return [
        ((x * 3 + y * 5 + offset) % 7) < 3
        for y in range(NAMETABLE_PIXEL_HEIGHT)
        for x in range(NAMETABLE_PIXEL_WIDTH)
    ]


def mask_to_framebuffer(mask: BackgroundOpaqueMask) -> Framebuffer:
    """Represent mask entries as colors so both viewport mappings can be compared."""
    return Framebuffer(
        width=NAMETABLE_PIXEL_WIDTH,
        height=NAMETABLE_PIXEL_HEIGHT,
        pixels=[OPAQUE_COLOR if value else BLACK for value in mask],
    )


def test_viewport_at_zero_uses_the_entire_left_mask():
    """
    Objective:
    With no horizontal offset, the visible opacity data is the left mask.
    """
    left = patterned_mask(offset=0)
    right = patterned_mask(offset=1)

    result = compose_horizontal_opaque_mask_viewport(left, right, viewport_x=0)

    assert result == left
    assert result is not left


def test_viewport_at_256_uses_the_entire_right_mask():
    """
    Objective:
    Logical X 256 begins at the first column of the right mask.
    """
    left = patterned_mask(offset=0)
    right = patterned_mask(offset=1)

    result = compose_horizontal_opaque_mask_viewport(left, right, viewport_x=256)

    assert result == right
    assert result is not right


def test_viewport_at_200_crosses_the_mask_seam_on_every_row():
    """
    Objective:
    Compose 56 columns from the left mask and 200 columns from the right mask while
    preserving every source Y row.
    """
    left = patterned_mask(offset=0)
    right = patterned_mask(offset=1)

    result = compose_horizontal_opaque_mask_viewport(left, right, viewport_x=200)

    expected: BackgroundOpaqueMask = []
    for y in range(NAMETABLE_PIXEL_HEIGHT):
        row_start = y * NAMETABLE_PIXEL_WIDTH
        row_end = row_start + NAMETABLE_PIXEL_WIDTH
        expected.extend(left[row_start + 200:row_end])
        expected.extend(right[row_start:row_start + 200])

    assert result == expected


def test_viewport_wraps_from_right_mask_back_to_left_mask():
    """
    Objective:
    A viewport beginning at logical X 300 consumes 212 right columns and then wraps
    to 44 left columns.
    """
    left = patterned_mask(offset=0)
    right = patterned_mask(offset=1)

    result = compose_horizontal_opaque_mask_viewport(left, right, viewport_x=300)

    expected: BackgroundOpaqueMask = []
    for y in range(NAMETABLE_PIXEL_HEIGHT):
        row_start = y * NAMETABLE_PIXEL_WIDTH
        row_end = row_start + NAMETABLE_PIXEL_WIDTH
        expected.extend(right[row_start + 44:row_end])
        expected.extend(left[row_start:row_start + 44])

    assert result == expected


def test_composition_does_not_mutate_source_masks():
    """
    Objective:
    Preserve source masks so framebuffer rendering, sprite priority, and hit detection
    can reuse deterministic source data.
    """
    left = patterned_mask(offset=0)
    right = patterned_mask(offset=1)
    left_before = list(left)
    right_before = list(right)

    result = compose_horizontal_opaque_mask_viewport(left, right, viewport_x=200)

    assert left == left_before
    assert right == right_before
    assert result is not left
    assert result is not right


def test_mask_and_framebuffer_compositors_use_identical_mapping():
    """
    Objective:
    Prevent visual background pixels from drifting away from the opacity information
    used for sprite priority and sprite-zero-hit decisions.
    """
    left_mask = patterned_mask(offset=0)
    right_mask = patterned_mask(offset=1)
    left_framebuffer = mask_to_framebuffer(left_mask)
    right_framebuffer = mask_to_framebuffer(right_mask)

    composed_mask = compose_horizontal_opaque_mask_viewport(
        left_mask,
        right_mask,
        viewport_x=200,
    )
    composed_framebuffer = compose_horizontal_framebuffer_viewport(
        left_framebuffer,
        right_framebuffer,
        viewport_x=200,
    )

    opacity_derived_from_pixels = [
        color == OPAQUE_COLOR
        for color in composed_framebuffer.pixels
    ]

    assert composed_mask == opacity_derived_from_pixels


def test_rejects_left_mask_with_wrong_entry_count():
    """
    Objective:
    Detect malformed left masks at the boundary rather than during coordinate lookup.
    """
    left = [False] * (MASK_SIZE - 1)
    right = [False] * MASK_SIZE

    with pytest.raises(ValueError, match="Left background opacity mask"):
        compose_horizontal_opaque_mask_viewport(left, right, viewport_x=0)


def test_rejects_right_mask_with_wrong_entry_count():
    """
    Objective:
    Apply the same fixed-size invariant to the right source mask.
    """
    left = [False] * MASK_SIZE
    right = [False] * (MASK_SIZE + 1)

    with pytest.raises(ValueError, match="Right background opacity mask"):
        compose_horizontal_opaque_mask_viewport(left, right, viewport_x=0)

测试函数 (8)

test_viewport_at_zero_uses_the_entire_left_mask
test_viewport_at_256_uses_the_entire_right_mask
test_viewport_at_200_crosses_the_mask_seam_on_every_row
test_viewport_wraps_from_right_mask_back_to_left_mask
test_composition_does_not_mutate_source_masks
test_mask_and_framebuffer_compositors_use_identical_mapping
test_rejects_left_mask_with_wrong_entry_count
test_rejects_right_mask_with_wrong_entry_count