324. Flag de mirroring vertical de iNES

Decodificar el mirroring horizontal/vertical de nametables a partir del bit 0 de iNES flags 6.

Lección 324 de 356 · tests/chapter_12_mirroring/test_324_ines_vertical_mirroring_flag.py

Archivo a actualizar

emulator/cartridge/ines.py

Referencia

https://www.nesdev.org/wiki/Mirroring#Nametable_Mirroring

Por qué existe este paso

Antes de implementar un viewport con scrolling, el emulador debe saber cómo el cartucho conecta los nametables lógicos del PPU sobre la RAM física de nametables.

El mirroring no voltea una imagen visualmente. Controla el mapeo de memoria entre las cuatro regiones lógicas de nametable:

$2000
$2400
$2800
$2C00

El bit 0 de iNES flags 6 selecciona el modo básico de mirroring:

bit 0 clear -> horizontal mirroring
bit 0 set   -> vertical mirroring

Para el alcance incremental actual, exponer esto como una única propiedad booleana

is_vertical_mirroring is False -> horizontal
is_vertical_mirroring is True  -> vertical

Ejemplo de implementación sugerido

FLAGS6_VERTICAL_MIRRORING = 1 << 0


@dataclass(frozen=True)
class INesHeader:
    prg_rom_banks: int
    chr_rom_banks: int
    mapper_number: int
    has_trainer: bool
    flags_6: int
    flags_7: int

    @property
    def is_vertical_mirroring(self) -> bool:
        return (self.flags_6 & FLAGS6_VERTICAL_MIRRORING) != 0

¿Por qué una propiedad calculada? flags_6 sigue siendo la única fuente de verdad y el constructor existente de INesHeader no necesita cambiar. Eso conserva los tests y el código llamante de versiones anteriores del tutorial.

Extensión futura

El mirroring de cuatro pantallas puede añadir más adelante una propiedad is_four_screen comprobada antes de is_vertical_mirroring. El almacenamiento y el enrutamiento de cuatro pantallas no se implementan aquí.

Fuera del alcance

cambiar Cartridge
cambiar Mapper000
cambiar el mapeo de nametables de PpuBus
RAM de nametables de cuatro pantallas
scrolling
fixtures de ROM comerciales

Ejecutar esta lección

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

Implementación de ejemplo

Ejemplo de implementación sugerido

FLAGS6_VERTICAL_MIRRORING = 1 << 0


@dataclass(frozen=True)
class INesHeader:
    prg_rom_banks: int
    chr_rom_banks: int
    mapper_number: int
    has_trainer: bool
    flags_6: int
    flags_7: int

    @property
    def is_vertical_mirroring(self) -> bool:
        return (self.flags_6 & FLAGS6_VERTICAL_MIRRORING) != 0

Ver código del testtest_324_ines_vertical_mirroring_flag.py

from emulator.cartridge.ines import (
    FLAGS6_VERTICAL_MIRRORING,
    INES_MAGIC,
    INesHeader,
    parse_ines_header,
)


def make_header_bytes(flags_6: int = 0, flags_7: int = 0) -> bytes:
    """Build a minimal 16-byte iNES header with configurable flag bytes."""
    return bytes([
        *INES_MAGIC,
        1,
        1,
        flags_6,
        flags_7,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
    ])


def test_flags6_vertical_mirroring_constant_names_bit_zero():
    """
    Objective:
    Give iNES flags 6 bit 0 a domain-specific name instead of repeating a magic
    binary literal.
    """
    assert FLAGS6_VERTICAL_MIRRORING == 1 << 0


def test_ines_header_exposes_vertical_mirroring_property():
    """
    Objective:
    Mirroring metadata should be available directly from an INesHeader instance.
    """
    header = INesHeader(
        prg_rom_banks=1,
        chr_rom_banks=1,
        mapper_number=0,
        has_trainer=False,
        flags_6=0,
        flags_7=0,
    )

    assert hasattr(header, "is_vertical_mirroring")
    assert isinstance(header.is_vertical_mirroring, bool)


def test_flags6_bit_zero_clear_means_horizontal_mirroring():
    """
    Objective:
    False means horizontal mirroring; it does not mean mirroring is disabled.
    """
    header = parse_ines_header(make_header_bytes(flags_6=0b0000_0000))

    assert header.is_vertical_mirroring is False


def test_flags6_bit_zero_set_means_vertical_mirroring():
    """
    Objective:
    Setting flags 6 bit 0 requests vertical nametable mirroring.
    """
    header = parse_ines_header(
        make_header_bytes(flags_6=FLAGS6_VERTICAL_MIRRORING)
    )

    assert header.is_vertical_mirroring is True


def test_unrelated_flags6_bits_do_not_select_vertical_mirroring():
    """
    Objective:
    Trainer and mapper bits must not be confused with the mirroring bit.
    """
    unrelated_bits = 0b1010_0100
    assert (unrelated_bits & FLAGS6_VERTICAL_MIRRORING) == 0

    header = parse_ines_header(make_header_bytes(flags_6=unrelated_bits))

    assert header.is_vertical_mirroring is False


def test_vertical_mirroring_bit_can_coexist_with_other_flags():
    """
    Objective:
    Mirroring decoding should inspect bit 0 without discarding trainer or mapper
    information from the same flags byte.
    """
    flags_6 = 0b0010_0101

    header = parse_ines_header(make_header_bytes(flags_6=flags_6))

    assert header.is_vertical_mirroring is True
    assert header.has_trainer is True
    assert header.mapper_number == 2


def test_mirroring_property_does_not_change_ines_header_constructor_shape():
    """
    Objective:
    The property is computed from existing flags_6 metadata, so historical direct
    INesHeader construction remains valid.
    """
    header = INesHeader(1, 1, 0, False, 0, 0)

    assert header.prg_rom_banks == 1
    assert header.chr_rom_banks == 1
    assert header.is_vertical_mirroring is False

Funciones de test (7)

test_flags6_vertical_mirroring_constant_names_bit_zero
test_ines_header_exposes_vertical_mirroring_property
test_flags6_bit_zero_clear_means_horizontal_mirroring
test_flags6_bit_zero_set_means_vertical_mirroring
test_unrelated_flags6_bits_do_not_select_vertical_mirroring
test_vertical_mirroring_bit_can_coexist_with_other_flags
test_mirroring_property_does_not_change_ines_header_constructor_shape