326. El mapper conserva el mirroring

Propagar los metadatos de mirroring de nametables de Cartridge a Mapper000.

Lección 326 de 356 · tests/chapter_12_mirroring/test_326_mapper_preserves_mirroring.py

Archivos a actualizar

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

Por qué existe este paso

PpuBus ya recibe el mapper del cartucho. Exponer el mirroring a través del mapper mantiene una única ruta de propiedad del hardware del cartucho:

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

Esto es preferible a conectar Cartridge directamente a PpuBus por separado. Mappers futuros pueden controlar el mirroring mediante registros del mapper, por lo que el mapper es la frontera útil a largo plazo.

Cambios de implementación sugeridos

# 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:
        ...

Compatibilidad de anotaciones

El protocolo puede usar anotaciones inmediatas o from __future__ import annotations. El test ejecutable resuelve los type hints antes de comprobar que el mirroring es un booleano, por lo que el contrato no depende de si Python almacena la anotación como bool o como la cadena "bool".

¿Por qué añadir un campo de Mapper000 con valor por defecto? Los tests históricos y el código del tutorial construyen Mapper000 con solo PRG y CHR ROM. Añadir un valor por defecto False conserva ese constructor y significa mirroring horizontal cuando no se proporcionan metadatos.

Significado

False -> horizontal mirroring
True  -> vertical mirroring

Fuera del alcance

cambiar el mapeo de direcciones de PpuBus
cambiar la propiedad de CpuBus
mirroring de cuatro pantallas
scrolling
fixtures de ROM comerciales

Ejecutar esta lección

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

Implementación de ejemplo

Cambios de implementación sugeridos

# 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:
        ...

Ver código del testtest_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:]

Funciones de test (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