322. PPU 精灵零命中位置

从当前 PPU 状态中提取精灵 0 重叠位置。

第 322 / 356 · tests/chapter_11_sprite_zero_hit/test_322_ppu_sprite_zero_hit_position.py

需要更新的文件

emulator/rendering/sprite_zero_hit.py

该步骤存在的原因

现有的纯辅助函数需要显式传入渲染数据

find_sprite_zero_hit_position(
    sprite_zero,
    pattern_table,
    background_opaque_mask,
)

该 API 对于聚焦的测试很有用,但未来的 Console 步骤是从一个 PPU 开始的。本步骤新增一个小型适配器,从当前 PPU 状态中提取所需数据,并委托给现有的纯辅助函数。

在当前项目规模下,将这两个函数都保留在 sprite_zero_hit.py 中是清晰合理的:

find_sprite_zero_hit_position(...)
    explicit data -> overlap position

ppu_sprite_zero_hit_position(ppu)
    PPU state -> explicit data -> overlap position

第二个函数是一个适配器,而不是另一种重叠算法。

所需的提取内容

只解码 OAM 条目 0
通过 ppu_background_to_opaque_mask(ppu) 构建背景不透明度掩码
使用 PPUCTRL 第 3 位选择精灵图案表
通过 PpuBus 读取 PATTERN_TABLE_SIZE 字节
委托给 find_sprite_zero_hit_position(...)

建议的实现示例

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE, decode_chr_tile
from emulator.ppu.ppu import CTRL_SPRITE_PATTERN_TABLE, PPU
from emulator.rendering.ppu_background_renderer import (
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
    ppu_background_to_opaque_mask,
)
from emulator.rendering.sprite_renderer import (
    SpriteEntry,
    decode_sprite_attributes,
    decode_sprite_entry,
)

...

def ppu_sprite_zero_hit_position(
    ppu: PPU,
) -> SpriteZeroHitPosition | None:
    sprite_zero = decode_sprite_entry(
        oam=ppu.oam,
        sprite_index=0,
    )

    background_opaque_mask = ppu_background_to_opaque_mask(ppu)

    sprite_pattern_table_base = (
        PATTERN_TABLE_1_ADDR
        if ppu.ctrl & CTRL_SPRITE_PATTERN_TABLE
        else PATTERN_TABLE_0_ADDR
    )

    sprite_pattern_table = bytes(
        ppu.ppu_bus.read(sprite_pattern_table_base + offset)
        for offset in range(PATTERN_TABLE_SIZE)
    )

    return find_sprite_zero_hit_position(
        sprite_zero=sprite_zero,
        pattern_table=sprite_pattern_table,
        background_opaque_mask=background_opaque_mask,
    )

重要区别

背景不透明度使用基于 PPUCTRL 第 4 位的背景图案表选择路径。精灵 0 的 CHR 数据则使用 PPUCTRL 第 3 位。两者的选择可能指向不同的图案表。

重要边界

该函数仅返回一个位置,不设置 PPUSTATUS,也不调用 PPU.set_sprite_zero_hit_position()。Console 接线仍是之后的步骤。

不在本步骤范围内

Console 接线
自动调度
PPUMASK 渲染使能规则
左边缘裁剪规则
x=255 硬件例外
OAM Y+1 修正
《超级马里奥兄弟》验证

运行本课

uv run pytest tests/chapter_11_sprite_zero_hit/test_322_ppu_sprite_zero_hit_position.py -v

示例实现

建议的实现示例

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE, decode_chr_tile
from emulator.ppu.ppu import CTRL_SPRITE_PATTERN_TABLE, PPU
from emulator.rendering.ppu_background_renderer import (
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
    ppu_background_to_opaque_mask,
)
from emulator.rendering.sprite_renderer import (
    SpriteEntry,
    decode_sprite_attributes,
    decode_sprite_entry,
)

...

def ppu_sprite_zero_hit_position(
    ppu: PPU,
) -> SpriteZeroHitPosition | None:
    sprite_zero = decode_sprite_entry(
        oam=ppu.oam,
        sprite_index=0,
    )

    background_opaque_mask = ppu_background_to_opaque_mask(ppu)

    sprite_pattern_table_base = (
        PATTERN_TABLE_1_ADDR
        if ppu.ctrl & CTRL_SPRITE_PATTERN_TABLE
        else PATTERN_TABLE_0_ADDR
    )

    sprite_pattern_table = bytes(
        ppu.ppu_bus.read(sprite_pattern_table_base + offset)
        for offset in range(PATTERN_TABLE_SIZE)
    )

    return find_sprite_zero_hit_position(
        sprite_zero=sprite_zero,
        pattern_table=sprite_pattern_table,
        background_opaque_mask=background_opaque_mask,
    )

查看测试代码test_322_ppu_sprite_zero_hit_position.py

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE
from emulator.ppu.ppu import CTRL_SPRITE_PATTERN_TABLE, PPU, SPRITE_ZERO_HIT
from emulator.rendering.ppu_background_renderer import (
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
)
from emulator.rendering.sprite_zero_hit import (
    find_sprite_zero_hit_position,
    ppu_sprite_zero_hit_position,
)
import emulator.rendering.sprite_zero_hit as sprite_zero_hit_module


def make_background_mask() -> list[bool]:
    return [False] * (256 * 240)


def test_ppu_adapter_and_pure_overlap_helper_live_in_same_focused_module():
    """
    Objective:
    Keep the two abstraction levels together while the sprite-zero-hit module remains
    small and cohesive.
    """
    assert callable(find_sprite_zero_hit_position)
    assert callable(ppu_sprite_zero_hit_position)
    assert find_sprite_zero_hit_position.__module__ == ppu_sprite_zero_hit_position.__module__


def test_ppu_sprite_zero_hit_position_decodes_only_oam_entry_zero(monkeypatch):
    """
    Objective:
    Sprite 0 hit uses the first four OAM bytes. Other sprites must not be substituted
    for OAM entry 0.
    """
    ppu = PPU()
    ppu.oam[0:4] = bytes([12, 7, 0x60, 34])
    ppu.oam[4:8] = bytes([99, 8, 0x00, 88])
    captured = {}

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )

    def fake_find_sprite_zero_hit_position(**kwargs):
        captured.update(kwargs)
        return None

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        fake_find_sprite_zero_hit_position,
    )

    ppu_sprite_zero_hit_position(ppu)

    sprite_zero = captured["sprite_zero"]
    assert sprite_zero.y == 12
    assert sprite_zero.tile_index == 7
    assert sprite_zero.attributes == 0x60
    assert sprite_zero.x == 34


def test_ppu_adapter_passes_background_mask_to_pure_helper_unchanged(monkeypatch):
    """
    Objective:
    Background extraction belongs to ppu_background_to_opaque_mask(). The adapter
    should pass its result directly to the pure overlap helper.
    """
    ppu = PPU()
    expected_mask = make_background_mask()
    expected_mask[123] = True
    captured = {}

    def fake_background_mask(received_ppu):
        assert received_ppu is ppu
        return expected_mask

    def fake_find_sprite_zero_hit_position(**kwargs):
        captured.update(kwargs)
        return None

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        fake_background_mask,
    )
    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        fake_find_sprite_zero_hit_position,
    )

    ppu_sprite_zero_hit_position(ppu)

    assert captured["background_opaque_mask"] is expected_mask


def test_ppu_adapter_uses_sprite_pattern_table_zero_when_ctrl_bit_is_clear(monkeypatch):
    """
    Objective:
    PPUCTRL bit 3 clear selects sprite pattern table $0000-$0FFF.
    """
    ppu = PPU()
    assert (ppu.ctrl & CTRL_SPRITE_PATTERN_TABLE) == 0
    ppu.ppu_bus.write(PATTERN_TABLE_0_ADDR, 0x11)
    ppu.ppu_bus.write(PATTERN_TABLE_1_ADDR, 0x22)
    captured = {}

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )

    def fake_find_sprite_zero_hit_position(**kwargs):
        captured.update(kwargs)
        return None

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        fake_find_sprite_zero_hit_position,
    )

    ppu_sprite_zero_hit_position(ppu)

    pattern_table = captured["pattern_table"]
    assert isinstance(pattern_table, bytes)
    assert len(pattern_table) == PATTERN_TABLE_SIZE
    assert pattern_table[0] == 0x11


def test_ppu_adapter_uses_sprite_pattern_table_one_when_ctrl_bit_is_set(monkeypatch):
    """
    Objective:
    PPUCTRL bit 3 set selects sprite pattern table $1000-$1FFF.
    """
    ppu = PPU()
    ppu.ctrl |= CTRL_SPRITE_PATTERN_TABLE
    ppu.ppu_bus.write(PATTERN_TABLE_0_ADDR, 0x11)
    ppu.ppu_bus.write(PATTERN_TABLE_1_ADDR, 0x22)
    captured = {}

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )

    def fake_find_sprite_zero_hit_position(**kwargs):
        captured.update(kwargs)
        return None

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        fake_find_sprite_zero_hit_position,
    )

    ppu_sprite_zero_hit_position(ppu)

    pattern_table = captured["pattern_table"]
    assert isinstance(pattern_table, bytes)
    assert len(pattern_table) == PATTERN_TABLE_SIZE
    assert pattern_table[0] == 0x22


def test_ppu_adapter_returns_pure_helper_result_unchanged(monkeypatch):
    """
    Objective:
    This adapter should not reinterpret or offset the position returned by the pure
    overlap helper.
    """
    ppu = PPU()
    expected_position = (45, 67)

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )
    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        lambda **kwargs: expected_position,
    )

    result = ppu_sprite_zero_hit_position(ppu)

    assert result is expected_position


def test_ppu_adapter_does_not_set_status_or_schedule_position(monkeypatch):
    """
    Objective:
    Step 322 only extracts and returns a position. PPU mutation belongs to the next
    Console orchestration step.
    """
    ppu = PPU()
    expected_position = (10, 20)

    monkeypatch.setattr(
        sprite_zero_hit_module,
        "ppu_background_to_opaque_mask",
        lambda received_ppu: make_background_mask(),
    )
    monkeypatch.setattr(
        sprite_zero_hit_module,
        "find_sprite_zero_hit_position",
        lambda **kwargs: expected_position,
    )

    result = ppu_sprite_zero_hit_position(ppu)

    assert result == expected_position
    assert (ppu.status & SPRITE_ZERO_HIT) == 0
    assert ppu.sprite_zero_hit_position is None

测试函数 (7)

test_ppu_adapter_and_pure_overlap_helper_live_in_same_focused_module
test_ppu_sprite_zero_hit_position_decodes_only_oam_entry_zero
test_ppu_adapter_passes_background_mask_to_pure_helper_unchanged
test_ppu_adapter_uses_sprite_pattern_table_zero_when_ctrl_bit_is_clear
test_ppu_adapter_uses_sprite_pattern_table_one_when_ctrl_bit_is_set
test_ppu_adapter_returns_pure_helper_result_unchanged
test_ppu_adapter_does_not_set_status_or_schedule_position