332. Nametable lógico de la PPU a framebuffer

Renderiza como framebuffer un nametable lógico seleccionado de la PPU.

Lección 332 de 356 · tests/chapter_13_scrolling/test_332_ppu_logical_nametable_to_framebuffer.py

Archivo a actualizar

emulator/rendering/ppu_background_renderer.py

Referencia

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

Por qué existe este paso

La función auxiliar original siempre renderizaba el nametable lógico $2000. El desplazamiento horizontal también necesita el nametable lógico adyacente, por lo que ahora la función auxiliar acepta uno de:

$2000, $2400, $2800, $2C00

Disposición de memoria relativa a la base seleccionada

base + $000-$3BF: 960 visible tile IDs
base + $3C0-$3FF: 64 attribute bytes

Compatibilidad

Omitir base_nametable_addr debe seguir renderizando $2000. Por lo tanto, el código llamante existente no necesita cambios.

Frontera de mirroring

El renderizado solicita direcciones lógicas a través de PpuBus. PpuBus sigue siendo responsable de asignar esas direcciones a la VRAM física con mirroring horizontal o vertical.

Fuera del alcance

seleccionar y componer dos framebuffers adyacentes
selección de direcciones de la máscara de opacidad
integración en Console
composición del viewport vertical
pygame

Implementación de ejemplo

# emulator/rendering/ppu_background_renderer.py

# --- NEW LINES: ACCEPTED LOGICAL NAMETABLE BASE ADDRESSES ---
LOGICAL_NAMETABLE_BASE_ADDRS = (
    0x2000,
    0x2400,
    0x2800,
    0x2C00,
)


def ppu_background_to_framebuffer(
    ppu: PPU,
    # --- NEW LINE: OPTIONAL LOGICAL NAMETABLE SELECTION ---
    base_nametable_addr: int = BASE_NAMETABLE_ADDR,
) -> Framebuffer:
    # --- NEW BLOCK: REJECT NON-NAMETABLE BASE ADDRESSES ---
    if base_nametable_addr not in LOGICAL_NAMETABLE_BASE_ADDRS:
        raise ValueError(
            "Logical nametable base address must be $2000, $2400, $2800, $2C00"
        )

    nametable_bytes = bytes(
        # --- UPDATED LINE: READ FROM THE SELECTED NAMETABLE ---
        ppu.ppu_bus.read(base_nametable_addr + offset)
        for offset in range(NAMETABLE_SIZE)
    )

    # --- NEW LINE: DERIVE THE SELECTED ATTRIBUTE-TABLE BASE ---
    attribute_table_base = base_nametable_addr + NAMETABLE_SIZE
    attribute_table = bytes(
        # --- UPDATED LINE: READ THE SELECTED ATTRIBUTE TABLE ---
        ppu.ppu_bus.read(attribute_table_base + offset)
        for offset in range(ATTR_TABLE_SIZE)
    )

   ... 
   # Everything remains the same below this point

Ejecutar esta lección

uv run pytest tests/chapter_13_scrolling/test_332_ppu_logical_nametable_to_framebuffer.py -v

Implementación de ejemplo

# emulator/rendering/ppu_background_renderer.py

# --- NEW LINES: ACCEPTED LOGICAL NAMETABLE BASE ADDRESSES ---
LOGICAL_NAMETABLE_BASE_ADDRS = (
    0x2000,
    0x2400,
    0x2800,
    0x2C00,
)


def ppu_background_to_framebuffer(
    ppu: PPU,
    # --- NEW LINE: OPTIONAL LOGICAL NAMETABLE SELECTION ---
    base_nametable_addr: int = BASE_NAMETABLE_ADDR,
) -> Framebuffer:
    # --- NEW BLOCK: REJECT NON-NAMETABLE BASE ADDRESSES ---
    if base_nametable_addr not in LOGICAL_NAMETABLE_BASE_ADDRS:
        raise ValueError(
            "Logical nametable base address must be $2000, $2400, $2800, $2C00"
        )

    nametable_bytes = bytes(
        # --- UPDATED LINE: READ FROM THE SELECTED NAMETABLE ---
        ppu.ppu_bus.read(base_nametable_addr + offset)
        for offset in range(NAMETABLE_SIZE)
    )

    # --- NEW LINE: DERIVE THE SELECTED ATTRIBUTE-TABLE BASE ---
    attribute_table_base = base_nametable_addr + NAMETABLE_SIZE
    attribute_table = bytes(
        # --- UPDATED LINE: READ THE SELECTED ATTRIBUTE TABLE ---
        ppu.ppu_bus.read(attribute_table_base + offset)
        for offset in range(ATTR_TABLE_SIZE)
    )

   ... 
   # Everything remains the same below this point

Ver código del testtest_332_ppu_logical_nametable_to_framebuffer.py

import pytest

from emulator.ppu.ppu import CTRL_BACKGROUND_PATTERN_TABLE, PPU
from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.nametable_renderer import NAMETABLE_SIZE
import emulator.rendering.ppu_background_renderer as background_renderer
from emulator.rendering.ppu_background_renderer import (
    ATTR_TABLE_SIZE,
    BASE_ATTR_TABLE_ADDR,
    BASE_NAMETABLE_ADDR,
    LOGICAL_NAMETABLE_BASE_ADDRS,
    PALETTE_RAM_ADDR,
    PATTERN_TABLE_1_ADDR,
    ppu_background_to_framebuffer,
)


class RecordingPpuBus:
    """Minimal bus double that records every logical address requested."""

    def __init__(self) -> None:
        self.read_addresses: list[int] = []

    def read(self, addr: int) -> int:
        self.read_addresses.append(addr)
        return addr & 0xFF


def replace_low_level_renderer(monkeypatch):
    """Capture extracted bytes without spending time decoding a full framebuffer."""
    captured: dict[str, bytes] = {}
    expected_framebuffer = Framebuffer()

    def fake_renderer(
        nametable_bytes: bytes,
        attribute_table: bytes,
        pattern_table_bytes: bytes,
        palette_ram: bytes,
    ) -> Framebuffer:
        captured["nametable"] = nametable_bytes
        captured["attributes"] = attribute_table
        captured["pattern_table"] = pattern_table_bytes
        captured["palette_ram"] = palette_ram
        return expected_framebuffer

    monkeypatch.setattr(
        background_renderer,
        "nametable_with_palette_ram_to_framebuffer",
        fake_renderer,
    )
    return captured, expected_framebuffer


@pytest.mark.parametrize("base", LOGICAL_NAMETABLE_BASE_ADDRS)
def test_selected_logical_base_reads_its_tile_and_attribute_ranges(monkeypatch, base):
    """
    Objective:
    Read tile IDs and attributes relative to each selected logical nametable base.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    replace_low_level_renderer(monkeypatch)

    ppu_background_to_framebuffer(ppu, base_nametable_addr=base)

    tile_reads = bus.read_addresses[:NAMETABLE_SIZE]
    attribute_start = NAMETABLE_SIZE
    attribute_end = attribute_start + ATTR_TABLE_SIZE
    attribute_reads = bus.read_addresses[attribute_start:attribute_end]

    assert tile_reads == list(range(base, base + NAMETABLE_SIZE))
    assert attribute_reads == list(
        range(base + NAMETABLE_SIZE, base + NAMETABLE_SIZE + ATTR_TABLE_SIZE)
    )


def test_omitted_base_preserves_historical_2000_behavior(monkeypatch):
    """
    Objective:
    Keep every existing one-argument caller compatible with the original helper.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    replace_low_level_renderer(monkeypatch)

    ppu_background_to_framebuffer(ppu)

    assert BASE_NAMETABLE_ADDR == 0x2000
    assert BASE_ATTR_TABLE_ADDR == 0x23C0
    assert bus.read_addresses[0] == BASE_NAMETABLE_ADDR
    assert bus.read_addresses[NAMETABLE_SIZE] == BASE_ATTR_TABLE_ADDR


def test_selected_nametable_still_uses_shared_pattern_and_palette_data(monkeypatch):
    """
    Objective:
    Generalizing nametable selection must not change PPUCTRL pattern-table selection
    or the shared palette-RAM address.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    ppu.ctrl = CTRL_BACKGROUND_PATTERN_TABLE
    captured, expected_framebuffer = replace_low_level_renderer(monkeypatch)

    result = ppu_background_to_framebuffer(
        ppu,
        base_nametable_addr=0x2400,
    )

    pattern_read_start = NAMETABLE_SIZE + ATTR_TABLE_SIZE
    palette_read_start = pattern_read_start + len(captured["pattern_table"])

    assert bus.read_addresses[pattern_read_start] == PATTERN_TABLE_1_ADDR
    assert bus.read_addresses[palette_read_start] == PALETTE_RAM_ADDR
    assert result is expected_framebuffer


@pytest.mark.parametrize("invalid_base", [0x0000, 0x23C0, 0x3000, 0x3F00])
def test_rejects_addresses_that_are_not_logical_nametable_bases(invalid_base):
    """
    Objective:
    Reject arbitrary addresses before performing partial or misleading bus reads.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)

    with pytest.raises(ValueError, match="Logical nametable base address"):
        ppu_background_to_framebuffer(
            ppu,
            base_nametable_addr=invalid_base,
        )

    assert bus.read_addresses == []


def test_renderer_requests_logical_addresses_and_leaves_mirroring_to_ppu_bus(monkeypatch):
    """
    Objective:
    The renderer must issue the selected logical address range without duplicating
    PpuBus nametable-normalization rules.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    replace_low_level_renderer(monkeypatch)

    ppu_background_to_framebuffer(ppu, base_nametable_addr=0x2C00)

    assert bus.read_addresses[0] == 0x2C00
    assert bus.read_addresses[NAMETABLE_SIZE - 1] == 0x2FBF
    assert bus.read_addresses[NAMETABLE_SIZE] == 0x2FC0
    assert bus.read_addresses[NAMETABLE_SIZE + ATTR_TABLE_SIZE - 1] == 0x2FFF

Funciones de test (5)

test_selected_logical_base_reads_its_tile_and_attribute_ranges
test_omitted_base_preserves_historical_2000_behavior
test_selected_nametable_still_uses_shared_pattern_and_palette_data
test_rejects_addresses_that_are_not_logical_nametable_bases
test_renderer_requests_logical_addresses_and_leaves_mirroring_to_ppu_bus