253. Mapeo de la VRAM de nametable en el bus de la PPU

Implementa el mapeo de direcciones de la VRAM de nametable en PpuBus.

Lección 253 de 356 · tests/chapter_03_ppu_memory_and_graphics_data/test_253_ppu_bus_nametable_vram_mapping.py

Referencia

https://www.nesdev.org/wiki/PPU_memory_map
https://www.nesdev.org/wiki/PPU_nametables

Archivo a modificar

emulator/bus/ppu_bus.py

Constantes a añadir

NAMETABLE_START = 0x2000
NAMETABLE_END = 0x3EFF
NAMETABLE_SIZE = 0x0800

¿Qué es un nametable? Un nametable es memoria de disposición del fondo. No almacena píxeles. Almacena números de tile que indican a la PPU qué tile de CHR dibujar en cada posición del fondo.

Ejemplo simple

PPU memory $2000 contains $24

Significado

the top-left background cell uses CHR tile index $24

La PPU expone cuatro áreas lógicas de nametable de 1KB

$2000-$23FF
$2400-$27FF
$2800-$2BFF
$2C00-$2FFF

El rango $3000-$3EFF duplica $2000-$2EFF.

Simplificación del tutorial

Por ahora, usa el gran almacenamiento de VRAM existente y normaliza las direcciones de nametable en una ventana simple de 2KB. Todavía no crees un objeto de RAM de nametable independiente.

Ejemplo de implementación sugerida

NAMETABLE_START = 0x2000
NAMETABLE_END = 0x3EFF
NAMETABLE_SIZE = 0x0800

def normalize_nametable_addr(self, addr: int) -> int:
    if 0x3000 <= addr <= 0x3EFF:
        addr -= 0x1000

    index = (addr - NAMETABLE_START) % NAMETABLE_SIZE
    return NAMETABLE_START + index

def read(self, addr: int) -> int:
    addr = addr & PPU_ADDRESS_MASK

    if CHR_START <= addr <= CHR_END:
        ...

    if NAMETABLE_START <= addr <= NAMETABLE_END:
        return self.vram.read(self.normalize_nametable_addr(addr))

    if PALETTE_START <= addr <= PALETTE_END:
        ...

    return self.vram.read(addr)

Fuera de alcance

duplicado horizontal/vertical del cartucho
duplicado de cuatro pantallas
interpretación de la tabla de atributos
renderizado
sacar el almacenamiento de nametable del gran array de VRAM

Ejecutar esta lección

uv run pytest tests/chapter_03_ppu_memory_and_graphics_data/test_253_ppu_bus_nametable_vram_mapping.py -v

Implementación de ejemplo

Constantes a añadir

NAMETABLE_START = 0x2000
NAMETABLE_END = 0x3EFF
NAMETABLE_SIZE = 0x0800

Ejemplo de implementación sugerida

NAMETABLE_START = 0x2000
NAMETABLE_END = 0x3EFF
NAMETABLE_SIZE = 0x0800

def normalize_nametable_addr(self, addr: int) -> int:
    if 0x3000 <= addr <= 0x3EFF:
        addr -= 0x1000

    index = (addr - NAMETABLE_START) % NAMETABLE_SIZE
    return NAMETABLE_START + index

def read(self, addr: int) -> int:
    addr = addr & PPU_ADDRESS_MASK

    if CHR_START <= addr <= CHR_END:
        ...

    if NAMETABLE_START <= addr <= NAMETABLE_END:
        return self.vram.read(self.normalize_nametable_addr(addr))

    if PALETTE_START <= addr <= PALETTE_END:
        ...

    return self.vram.read(addr)

Ver código del testtest_253_ppu_bus_nametable_vram_mapping.py

from emulator.bus.ppu_bus import NAMETABLE_END, NAMETABLE_SIZE, NAMETABLE_START, PpuBus


def test_ppu_bus_declares_nametable_mapping_constants():
    """
    Objective:
    Name the PPU nametable range and the current 2KB backing window size.
    """
    assert NAMETABLE_START == 0x2000
    assert NAMETABLE_END == 0x3EFF
    assert NAMETABLE_SIZE == 0x0800


def test_ppu_bus_can_read_back_direct_nametable_address_write():
    """
    Objective:
    The first nametable address should be readable and writable through PpuBus.
    """
    bus = PpuBus()

    bus.write(0x2000, 0x24)

    assert bus.read(0x2000) == 0x24


def test_second_2kb_nametable_area_wraps_to_current_backing_window():
    """
    Objective:
    In this simplified 2KB model, $2800 wraps to $2000.

    This is not final cartridge mirroring behavior. It is the current tutorial
    model for keeping nametable storage inside the large VRAM backing.
    """
    bus = PpuBus()

    bus.write(0x2800, 0x55)

    assert bus.read(0x2000) == 0x55
    assert bus.read(0x2800) == 0x55


def test_end_of_logical_nametable_range_wraps_inside_2kb_window():
    """
    Objective:
    $2FFF maps to the last byte of the current 2KB nametable window: $27FF.
    """
    bus = PpuBus()

    bus.write(0x2FFF, 0x66)

    assert bus.read(0x27FF) == 0x66
    assert bus.read(0x2FFF) == 0x66


def test_3000_nametable_mirror_maps_to_2000():
    """
    Objective:
    $3000-$3EFF mirrors $2000-$2EFF. The first mirror address maps to $2000.
    """
    bus = PpuBus()

    bus.write(0x3000, 0x77)

    assert bus.read(0x2000) == 0x77
    assert bus.read(0x3000) == 0x77


def test_last_nametable_mirror_address_maps_through_2kb_window():
    """
    Objective:
    $3EFF first mirrors to $2EFF, then the current 2KB model maps that to $26FF.
    """
    bus = PpuBus()

    bus.write(0x3EFF, 0x88)

    assert bus.read(0x26FF) == 0x88
    assert bus.read(0x3EFF) == 0x88


def test_palette_range_remains_separate_from_nametable_range():
    """
    Objective:
    $3F00 is palette memory, not a nametable mirror.

    This protects the route order:
        CHR -> nametable -> palette
    """
    bus = PpuBus()

    bus.write(0x3000, 0x11)
    bus.write(0x3F00, 0x22)

    assert bus.read(0x2000) == 0x11
    assert bus.read(0x3F00) == 0x22

Funciones de test (7)

test_ppu_bus_declares_nametable_mapping_constants
test_ppu_bus_can_read_back_direct_nametable_address_write
test_second_2kb_nametable_area_wraps_to_current_backing_window
test_end_of_logical_nametable_range_wraps_inside_2kb_window
test_3000_nametable_mirror_maps_to_2000
test_last_nametable_mirror_address_maps_through_2kb_window
test_palette_range_remains_separate_from_nametable_range