326. Mapper 保留镜像信息

将名称表镜像元数据从 Cartridge 传递到 Mapper000。

第 326 / 356 · tests/chapter_12_mirroring/test_326_mapper_preserves_mirroring.py

需要更新的文件

emulator/cartridge/mapper000.py
emulator/cartridge/mapper_factory.py
emulator/cartridge/mapper_interface.py

该步骤存在的原因

PpuBus 已经获得了卡带 mapper。通过 mapper 暴露镜像信息,可以保持单一的卡带硬件所有权路径:

INesHeader
    -> Cartridge
    -> Mapper000
    -> PpuBus (next step)

这比让 Cartridge 单独直接连接到 PpuBus 更可取。未来的 mapper 可能会通过 mapper 寄存器来控制镜像,因此 mapper 是更有价值的长期边界。

建议的实现改动

# emulator/cartridge/mapper000.py

@dataclass
class Mapper000:
    prg_rom: bytes
    chr_rom: bytes

    # --- NEW LINE ---
    is_vertical_mirroring: bool = False
    # --- END NEW LINE ---

    ...


# emulator/cartridge/mapper_factory.py

def create_mapper(cartridge: Cartridge):
    if cartridge.mapper_number == 0:
        return Mapper000(
            prg_rom=cartridge.prg_rom,
            chr_rom=cartridge.chr_rom,

            # --- NEW LINE ---
            is_vertical_mirroring=cartridge.is_vertical_mirroring,
            # --- END NEW LINE ---
        )

    ...


# emulator/cartridge/mapper_interface.py

class MapperInterface(Protocol):
    # --- NEW LINE ---
    is_vertical_mirroring: bool
    # --- END NEW LINE ---

    def read_prg(self, addr: int) -> int:
        ...

注解兼容性

协议既可以使用即时注解,也可以使用 from __future__ import annotations。可执行测试会先解析类型提示,再检查镜像值是否为布尔类型,因此该契约不依赖于 Python 是将注解存储为 bool 还是字符串 "bool"。

为什么要为 Mapper000 追加一个带默认值的字段?历史上的测试和教程代码在构造 Mapper000 时只传入 PRG 和 CHR ROM。追加一个默认为 False 的字段可以保留该构造方式,并意味着在未提供元数据时使用水平镜像。

含义

False -> horizontal mirroring
True  -> vertical mirroring

不在本步骤范围内

修改 PpuBus 的地址映射
修改 CpuBus 的所有权
四屏镜像
卷动
商业 ROM 测试夹具

运行本课

uv run pytest tests/chapter_12_mirroring/test_326_mapper_preserves_mirroring.py -v

示例实现

建议的实现改动

# emulator/cartridge/mapper000.py

@dataclass
class Mapper000:
    prg_rom: bytes
    chr_rom: bytes

    # --- NEW LINE ---
    is_vertical_mirroring: bool = False
    # --- END NEW LINE ---

    ...


# emulator/cartridge/mapper_factory.py

def create_mapper(cartridge: Cartridge):
    if cartridge.mapper_number == 0:
        return Mapper000(
            prg_rom=cartridge.prg_rom,
            chr_rom=cartridge.chr_rom,

            # --- NEW LINE ---
            is_vertical_mirroring=cartridge.is_vertical_mirroring,
            # --- END NEW LINE ---
        )

    ...


# emulator/cartridge/mapper_interface.py

class MapperInterface(Protocol):
    # --- NEW LINE ---
    is_vertical_mirroring: bool
    # --- END NEW LINE ---

    def read_prg(self, addr: int) -> int:
        ...

查看测试代码test_326_mapper_preserves_mirroring.py

from typing import get_type_hints

from emulator.cartridge.cartridge import Cartridge
from emulator.cartridge.mapper000 import Mapper000
from emulator.cartridge.mapper_factory import create_mapper
from emulator.cartridge.mapper_interface import MapperInterface


def make_cartridge(is_vertical_mirroring: bool) -> Cartridge:
    return Cartridge(
        prg_rom=bytes([0xEA] * (16 * 1024)),
        chr_rom=bytes([0x00] * (8 * 1024)),
        mapper_number=0,
        is_vertical_mirroring=is_vertical_mirroring,
    )


def test_mapper_interface_exposes_vertical_mirroring_metadata():
    """
    Objective:
    PpuBus should eventually be able to obtain mirroring through the common mapper
    contract rather than depending directly on Cartridge.
    """
    assert get_type_hints(MapperInterface)["is_vertical_mirroring"] is bool


def test_direct_mapper000_construction_defaults_to_horizontal_mirroring():
    """
    Objective:
    Preserve the historical two-argument Mapper000 constructor.
    """
    mapper = Mapper000(
        prg_rom=bytes([0xEA] * (16 * 1024)),
        chr_rom=bytes([0x00] * (8 * 1024)),
    )

    assert mapper.is_vertical_mirroring is False


def test_direct_mapper000_construction_can_request_vertical_mirroring():
    """
    Objective:
    Mapper000 can explicitly represent fixed vertical cartridge wiring.
    """
    mapper = Mapper000(
        prg_rom=bytes([0xEA] * (16 * 1024)),
        chr_rom=bytes([0x00] * (8 * 1024)),
        is_vertical_mirroring=True,
    )

    assert mapper.is_vertical_mirroring is True


def test_mapper_factory_preserves_horizontal_cartridge_mirroring():
    """
    Objective:
    A horizontal Cartridge should create a horizontal Mapper000.
    """
    cartridge = make_cartridge(is_vertical_mirroring=False)

    mapper = create_mapper(cartridge)

    assert isinstance(mapper, Mapper000)
    assert mapper.is_vertical_mirroring is False


def test_mapper_factory_preserves_vertical_cartridge_mirroring():
    """
    Objective:
    A vertical Cartridge should create a vertical Mapper000.
    """
    cartridge = make_cartridge(is_vertical_mirroring=True)

    mapper = create_mapper(cartridge)

    assert isinstance(mapper, Mapper000)
    assert mapper.is_vertical_mirroring is True


def test_mapper_factory_still_forwards_original_rom_data():
    """
    Objective:
    Adding mirroring metadata must not alter or copy away the existing PRG/CHR
    ownership inputs.
    """
    cartridge = make_cartridge(is_vertical_mirroring=True)

    mapper = create_mapper(cartridge)

    assert mapper.prg_rom is cartridge.prg_rom
    assert mapper.chr_rom is cartridge.chr_rom


def test_new_mapper_metadata_is_appended_after_historical_fields():
    """
    Objective:
    Preserve positional compatibility while allowing optional mapper metadata.
    """
    field_names = list(Mapper000.__dataclass_fields__)

    assert field_names[:2] == ["prg_rom", "chr_rom"]
    assert "is_vertical_mirroring" in field_names[2:]

测试函数 (7)

test_mapper_interface_exposes_vertical_mirroring_metadata
test_direct_mapper000_construction_defaults_to_horizontal_mirroring
test_direct_mapper000_construction_can_request_vertical_mirroring
test_mapper_factory_preserves_horizontal_cartridge_mirroring
test_mapper_factory_preserves_vertical_cartridge_mirroring
test_mapper_factory_still_forwards_original_rom_data
test_new_mapper_metadata_is_appended_after_historical_fields