333. Nametable lógico de la PPU a máscara de opacidad

Construye una máscara de opacidad a partir de un nametable lógico seleccionado de la PPU.

Lección 333 de 356 · tests/chapter_13_scrolling/test_333_ppu_logical_nametable_to_opaque_mask.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 existente construye la máscara que usan la prioridad de sprites y la detección de sprite-zero-hit, pero originalmente solo lee el nametable lógico $2000. El desplazamiento horizontal también necesita la máscara perteneciente al nametable lógico adyacente.

Compatibilidad

Omitir base_nametable_addr sigue seleccionando $2000, por lo que el código llamante existente de Console y de sprite-zero hit sigue siendo válido hasta que la integración del viewport se realice deliberadamente.

Entradas de opacidad

960 IDs de tile del nametable lógico seleccionado
la tabla de patrones de fondo seleccionada por el bit 4 de PPUCTRL

La opacidad no usa bytes de atributos, RAM de paleta ni colores RGB finales.

Fuera del alcance

componer las máscaras izquierda y derecha
renderizado de framebuffer
integración en Console
integración del viewport del sprite-zero-hit
desplazamiento vertical

Implementación de ejemplo completa

# emulator/rendering/ppu_background_renderer.py

def ppu_background_to_opaque_mask(
    ppu: PPU,
    # --- NEW LINE: OPTIONAL LOGICAL NAMETABLE SELECTION ---
    base_nametable_addr: int = BASE_NAMETABLE_ADDR,
) -> BackgroundOpaqueMask:
    # --- 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)
    )

    ...
    # Everything remains the same below this point.

Ejecutar esta lección

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

Implementación de ejemplo

Implementación de ejemplo completa

# emulator/rendering/ppu_background_renderer.py

def ppu_background_to_opaque_mask(
    ppu: PPU,
    # --- NEW LINE: OPTIONAL LOGICAL NAMETABLE SELECTION ---
    base_nametable_addr: int = BASE_NAMETABLE_ADDR,
) -> BackgroundOpaqueMask:
    # --- 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)
    )

    ...
    # Everything remains the same below this point.

Ver código del testtest_333_ppu_logical_nametable_to_opaque_mask.py

import pytest

from emulator.ppu.ppu import CTRL_BACKGROUND_PATTERN_TABLE, PPU
from emulator.rendering.nametable_renderer import BackgroundOpaqueMask, NAMETABLE_SIZE
import emulator.rendering.ppu_background_renderer as background_renderer
from emulator.rendering.ppu_background_renderer import (
    BASE_NAMETABLE_ADDR,
    LOGICAL_NAMETABLE_BASE_ADDRS,
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
    ppu_background_to_opaque_mask,
)


class RecordingPpuBus:
    """Minimal bus double that records each logical read request."""

    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_mask_builder(monkeypatch):
    """Capture extracted bytes while keeping this test focused on PPU adaptation."""
    captured: dict[str, bytes] = {}
    expected_mask: BackgroundOpaqueMask = [False, True]

    def fake_builder(
        pattern_table: bytes,
        nametable: bytes,
    ) -> BackgroundOpaqueMask:
        captured["pattern_table"] = pattern_table
        captured["nametable"] = nametable
        return expected_mask

    monkeypatch.setattr(
        background_renderer,
        "build_background_opaque_mask",
        fake_builder,
    )
    return captured, expected_mask


@pytest.mark.parametrize("base", LOGICAL_NAMETABLE_BASE_ADDRS)
def test_selected_logical_base_reads_its_visible_tile_range(monkeypatch, base):
    """
    Objective:
    Read all 960 tile IDs relative to each accepted logical nametable base.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    replace_mask_builder(monkeypatch)

    ppu_background_to_opaque_mask(ppu, base_nametable_addr=base)

    assert bus.read_addresses[:NAMETABLE_SIZE] == list(
        range(base, base + NAMETABLE_SIZE)
    )


def test_omitted_base_preserves_historical_2000_behavior(monkeypatch):
    """
    Objective:
    Keep existing one-argument Console and sprite-zero-hit callers compatible.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    replace_mask_builder(monkeypatch)

    ppu_background_to_opaque_mask(ppu)

    assert bus.read_addresses[0] == BASE_NAMETABLE_ADDR


@pytest.mark.parametrize(
    ("ctrl", "expected_pattern_base"),
    [
        (0, PATTERN_TABLE_0_ADDR),
        (CTRL_BACKGROUND_PATTERN_TABLE, PATTERN_TABLE_1_ADDR),
    ],
)
def test_selected_nametable_preserves_ppuctrl_pattern_table_selection(
    monkeypatch,
    ctrl,
    expected_pattern_base,
):
    """
    Objective:
    Nametable selection and background pattern-table selection remain independent.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    ppu.ctrl = ctrl
    captured, expected_mask = replace_mask_builder(monkeypatch)

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

    assert bus.read_addresses[NAMETABLE_SIZE] == expected_pattern_base
    assert len(captured["nametable"]) == NAMETABLE_SIZE
    assert result is expected_mask


def test_mask_extraction_does_not_read_attributes_or_palette_ram(monkeypatch):
    """
    Objective:
    Keep opacity based only on tile IDs and CHR color indexes.

    After 960 nametable reads, every remaining read must belong to the selected
    4096-byte pattern table.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    replace_mask_builder(monkeypatch)

    ppu_background_to_opaque_mask(ppu, base_nametable_addr=0x2400)

    pattern_reads = bus.read_addresses[NAMETABLE_SIZE:]

    assert pattern_reads == list(range(0x0000, 0x1000))


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

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

    assert bus.read_addresses == []

Funciones de test (5)

test_selected_logical_base_reads_its_visible_tile_range
test_omitted_base_preserves_historical_2000_behavior
test_selected_nametable_preserves_ppuctrl_pattern_table_selection
test_mask_extraction_does_not_read_attributes_or_palette_ram
test_rejects_addresses_that_are_not_logical_nametable_bases