325. Cartridge conserva el mirroring

Conservar los metadatos decodificados de mirroring de nametables en Cartridge.

Lección 325 de 356 · tests/chapter_12_mirroring/test_325_cartridge_preserves_mirroring.py

Archivo a actualizar

emulator/cartridge/cartridge.py

Por qué existe este paso

El paso 324 decodifica el bit 0 de iNES flags 6 mediante

INesHeader.is_vertical_mirroring

Esa información debe sobrevivir tras el parseo para que pasos posteriores de mapper y PpuBus puedan elegir el mapeo de direcciones de nametable correcto.

Ruta de metadatos para este paso

iNES flags 6
    -> INesHeader.is_vertical_mirroring
    -> Cartridge.is_vertical_mirroring

Cambios de implementación sugeridos

@dataclass
class Cartridge:
    prg_rom: bytes
    chr_rom: bytes
    mapper_number: int
    chr_ram: bytearray | None = None

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


@classmethod
def from_ines_bytes(cls, data: bytes) -> "Cartridge":
    ines_rom = parse_ines_rom(data)

    return cls(
        prg_rom=ines_rom.prg_rom,
        chr_rom=ines_rom.chr_rom,
        mapper_number=ines_rom.header.mapper_number,

        # --- NEW LINE ---
        is_vertical_mirroring=ines_rom.header.is_vertical_mirroring,
        # --- END NEW LINE ---
    )

¿Por qué añadir un campo con valor por defecto? El código histórico del tutorial construye Cartridge directamente con tres o cuatro argumentos posicionales. Añadir un campo con valor por defecto conserva esas formas del constructor mientras permite que las ROM parseadas proporcionen metadatos reales.

Significado

False -> horizontal mirroring
True  -> vertical mirroring

Fuera del alcance

cambiar Mapper000
cambiar MapperInterface
cambiar mapper_factory
cambiar el mapeo de nametables de PpuBus
mirroring de cuatro pantallas
scrolling
fixtures de ROM comerciales

Ejecutar esta lección

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

Implementación de ejemplo

Cambios de implementación sugeridos

@dataclass
class Cartridge:
    prg_rom: bytes
    chr_rom: bytes
    mapper_number: int
    chr_ram: bytearray | None = None

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


@classmethod
def from_ines_bytes(cls, data: bytes) -> "Cartridge":
    ines_rom = parse_ines_rom(data)

    return cls(
        prg_rom=ines_rom.prg_rom,
        chr_rom=ines_rom.chr_rom,
        mapper_number=ines_rom.header.mapper_number,

        # --- NEW LINE ---
        is_vertical_mirroring=ines_rom.header.is_vertical_mirroring,
        # --- END NEW LINE ---
    )

Ver código del testtest_325_cartridge_preserves_mirroring.py

from emulator.cartridge.cartridge import Cartridge
from emulator.cartridge.ines import INES_MAGIC


def make_ines_rom(
    flags_6: int,
    prg_banks: int = 1,
    chr_banks: int = 1,
) -> bytes:
    """Build a synthetic iNES ROM with valid PRG and CHR payload sizes."""
    header = bytes([
        *INES_MAGIC,
        prg_banks,
        chr_banks,
        flags_6,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
    ])
    prg_rom = bytes([0xEA] * (prg_banks * 16 * 1024))
    chr_rom = bytes([0x00] * (chr_banks * 8 * 1024))
    return header + prg_rom + chr_rom


def test_direct_cartridge_construction_defaults_to_horizontal_mirroring():
    """
    Objective:
    Existing direct constructors remain valid, and a missing mirroring argument uses
    the flags-bit-clear interpretation: horizontal.
    """
    cartridge = Cartridge(
        prg_rom=bytes([0xEA]),
        chr_rom=bytes([0x00]),
        mapper_number=0,
    )

    assert cartridge.is_vertical_mirroring is False


def test_direct_cartridge_construction_can_request_vertical_mirroring():
    """
    Objective:
    Synthetic tests and future cartridge builders can explicitly provide vertical
    mirroring metadata.
    """
    cartridge = Cartridge(
        prg_rom=bytes([0xEA]),
        chr_rom=bytes([0x00]),
        mapper_number=0,
        is_vertical_mirroring=True,
    )

    assert cartridge.is_vertical_mirroring is True


def test_old_fourth_positional_argument_still_represents_chr_ram():
    """
    Objective:
    Appending mirroring metadata must not reinterpret the historical fourth
    positional argument.
    """
    chr_ram = bytearray(8 * 1024)

    cartridge = Cartridge(
        bytes([0xEA]),
        bytes(),
        0,
        chr_ram,
    )

    assert cartridge.chr_ram is chr_ram
    assert cartridge.is_vertical_mirroring is False


def test_horizontal_ines_header_produces_horizontal_cartridge():
    """
    Objective:
    iNES flags 6 bit 0 clear should remain False after the ROM becomes a Cartridge.
    """
    cartridge = Cartridge.from_ines_bytes(
        make_ines_rom(flags_6=0b0000_0000)
    )

    assert cartridge.is_vertical_mirroring is False


def test_vertical_ines_header_produces_vertical_cartridge():
    """
    Objective:
    iNES flags 6 bit 0 set should remain True after the ROM becomes a Cartridge.
    """
    cartridge = Cartridge.from_ines_bytes(
        make_ines_rom(flags_6=0b0000_0001)
    )

    assert cartridge.is_vertical_mirroring is True


def test_mirroring_propagation_preserves_existing_cartridge_data():
    """
    Objective:
    Adding metadata must not alter PRG ROM, CHR ROM, or mapper decoding.
    """
    data = make_ines_rom(
        flags_6=0b0010_0001,
        prg_banks=1,
        chr_banks=1,
    )

    cartridge = Cartridge.from_ines_bytes(data)

    assert cartridge.mapper_number == 2
    assert len(cartridge.prg_rom) == 16 * 1024
    assert len(cartridge.chr_rom) == 8 * 1024
    assert cartridge.is_vertical_mirroring is True


def test_new_metadata_is_appended_after_historical_cartridge_fields():
    """
    Objective:
    Preserve the positional compatibility invariant without freezing Cartridge
    against additional optional metadata in later tutorial steps.
    """
    field_names = list(Cartridge.__dataclass_fields__)
    historical_prefix = [
        "prg_rom",
        "chr_rom",
        "mapper_number",
        "chr_ram",
    ]

    assert field_names[: len(historical_prefix)] == historical_prefix
    assert "is_vertical_mirroring" in field_names[len(historical_prefix):]

Funciones de test (7)

test_direct_cartridge_construction_defaults_to_horizontal_mirroring
test_direct_cartridge_construction_can_request_vertical_mirroring
test_old_fourth_positional_argument_still_represents_chr_ram
test_horizontal_ines_header_produces_horizontal_cartridge
test_vertical_ines_header_produces_vertical_cartridge
test_mirroring_propagation_preserves_existing_cartridge_data
test_new_metadata_is_appended_after_historical_cartridge_fields