326. Mapper сохраняет зеркалирование

Передать метаданные зеркалирования nametable из 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 уже получает маппер картриджа. Предоставление зеркалирования через маппер сохраняет единый путь владения аппаратной частью картриджа:

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

Это предпочтительнее, чем отдельно соединять Cartridge напрямую с PpuBus. Будущие мапперы могут управлять зеркалированием через регистры маппера, поэтому маппер — это полезная долгосрочная граница.

Предлагаемые изменения реализации

# 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