313. De fondo de la PPU a máscara de opacidad

Construye una máscara de opacidad de fondo a partir de la memoria de fondo actual de la PPU.

Lección 313 de 356 · tests/chapter_09_sprite_rendering/test_313_ppu_background_to_opaque_mask.py

Archivo a actualizar

emulator/rendering/ppu_background_renderer.py

Por qué existe este paso

El paso 310 añadió el ayudante puro

build_background_opaque_mask(pattern_table, nametable)

Ese ayudante trabaja a partir de bytes en bruto. Este paso añade el equivalente a nivel de PPU de:

ppu_background_to_framebuffer(ppu)

El nuevo ayudante debería ser

ppu_background_to_opaque_mask(ppu)

Es muy similar a ppu_background_to_framebuffer(), pero necesita menos información.

ppu_background_to_framebuffer() necesita:

bytes visibles de la tabla de nombres
bytes de la tabla de atributos
bytes de la tabla de patrones de fondo seleccionada
bytes de la RAM de paletas

porque produce píxeles RGB.

ppu_background_to_opaque_mask() solo necesita:

bytes visibles de la tabla de nombres
bytes de la tabla de patrones de fondo seleccionada

porque la opacidad depende únicamente de:

CHR color index != 0

La tabla de atributos y la RAM de paletas no afectan a la opacidad.

Implementación de ejemplo

def ppu_background_to_opaque_mask(ppu: PPU) -> BackgroundOpaqueMask:
    nametable_bytes = bytes(
        ppu.ppu_bus.read(BASE_NAMETABLE_ADDR + offset)
        for offset in range(NAMETABLE_SIZE)
    )

    pattern_table_base = (
        PATTERN_TABLE_1_ADDR
        if ppu.ctrl & CTRL_BACKGROUND_PATTERN_TABLE
        else PATTERN_TABLE_0_ADDR
    )

    pattern_table_bytes = bytes(
        ppu.ppu_bus.read(pattern_table_base + offset)
        for offset in range(PATTERN_TABLE_SIZE)
    )

    return build_background_opaque_mask(
        pattern_table=pattern_table_bytes,
        nametable=nametable_bytes,
    )

Importante

Este paso todavía no modifica Console.render_framebuffer(). El siguiente paso conectará Console para que llame a este ayudante y pase la máscara al compositor.

Fuera de alcance

cambiar emulator/console.py
pasar la máscara a composite_background_and_sprites()
sprite 0 hit
desbordamiento de sprites
pygame

Ejecutar esta lección

uv run pytest tests/chapter_09_sprite_rendering/test_313_ppu_background_to_opaque_mask.py -v

Implementación de ejemplo

def ppu_background_to_opaque_mask(ppu: PPU) -> BackgroundOpaqueMask:
    nametable_bytes = bytes(
        ppu.ppu_bus.read(BASE_NAMETABLE_ADDR + offset)
        for offset in range(NAMETABLE_SIZE)
    )

    pattern_table_base = (
        PATTERN_TABLE_1_ADDR
        if ppu.ctrl & CTRL_BACKGROUND_PATTERN_TABLE
        else PATTERN_TABLE_0_ADDR
    )

    pattern_table_bytes = bytes(
        ppu.ppu_bus.read(pattern_table_base + offset)
        for offset in range(PATTERN_TABLE_SIZE)
    )

    return build_background_opaque_mask(
        pattern_table=pattern_table_bytes,
        nametable=nametable_bytes,
    )

Ver código del testtest_313_ppu_background_to_opaque_mask.py

import inspect

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE
from emulator.ppu.ppu import CTRL_BACKGROUND_PATTERN_TABLE, PPU
from emulator.rendering.nametable_renderer import (
    NAMETABLE_SIZE,
    build_background_opaque_mask,
)
from emulator.rendering.ppu_background_renderer import (
    BASE_NAMETABLE_ADDR,
    PATTERN_TABLE_0_ADDR,
    PATTERN_TABLE_1_ADDR,
    ppu_background_to_opaque_mask,
)


def set_tile_row_to_color_index_in_ppu(
    ppu: PPU,
    pattern_table_base: int,
    tile_id: int,
    row: int,
    color_index: int,
) -> None:
    """Write one synthetic CHR tile row into PPU pattern-table memory."""
    tile_offset = tile_id * 16
    low_bit = color_index & 0b01
    high_bit = (color_index >> 1) & 0b01

    ppu.ppu_bus.write(pattern_table_base + tile_offset + row, 0xFF if low_bit else 0x00)
    ppu.ppu_bus.write(pattern_table_base + tile_offset + 8 + row, 0xFF if high_bit else 0x00)


def read_bytes_from_ppu(ppu: PPU, start: int, size: int) -> bytes:
    """Read a byte range from PPU memory through PpuBus."""
    return bytes(ppu.ppu_bus.read(start + offset) for offset in range(size))


def test_ppu_background_to_opaque_mask_function_exists():
    """
    Objective:
    Expose one helper for converting current PPU background memory into an opacity
    mask.
    """
    assert callable(ppu_background_to_opaque_mask)


def test_ppu_background_to_opaque_mask_returns_one_entry_per_visible_pixel():
    """
    Objective:
    The PPU-level helper should return the same per-pixel mask shape as the pure
    nametable helper.
    """
    ppu = PPU()

    mask = ppu_background_to_opaque_mask(ppu)

    assert len(mask) == 256 * 240


def test_ppu_background_to_opaque_mask_reads_visible_nametable_tile_ids():
    """
    Objective:
    The helper should read tile IDs from visible nametable memory at $2000-$23BF.
    """
    ppu = PPU()
    ppu.ppu_bus.write(BASE_NAMETABLE_ADDR, 1)
    set_tile_row_to_color_index_in_ppu(
        ppu=ppu,
        pattern_table_base=PATTERN_TABLE_0_ADDR,
        tile_id=1,
        row=0,
        color_index=1,
    )

    mask = ppu_background_to_opaque_mask(ppu)

    assert mask[0] is True


def test_ppu_background_to_opaque_mask_uses_pattern_table_zero_when_background_bit_is_clear():
    """
    Objective:
    If PPUCTRL bit 4 is clear, opacity comes from background pattern table $0000.
    """
    ppu = PPU()
    assert (ppu.ctrl & CTRL_BACKGROUND_PATTERN_TABLE) == 0

    ppu.ppu_bus.write(BASE_NAMETABLE_ADDR, 1)
    set_tile_row_to_color_index_in_ppu(
        ppu=ppu,
        pattern_table_base=PATTERN_TABLE_0_ADDR,
        tile_id=1,
        row=0,
        color_index=1,
    )
    set_tile_row_to_color_index_in_ppu(
        ppu=ppu,
        pattern_table_base=PATTERN_TABLE_1_ADDR,
        tile_id=1,
        row=0,
        color_index=0,
    )

    mask = ppu_background_to_opaque_mask(ppu)

    assert mask[0] is True


def test_ppu_background_to_opaque_mask_uses_pattern_table_one_when_background_bit_is_set():
    """
    Objective:
    If PPUCTRL bit 4 is set, opacity comes from background pattern table $1000.
    """
    ppu = PPU()
    ppu.write_register(0x2000, CTRL_BACKGROUND_PATTERN_TABLE)

    ppu.ppu_bus.write(BASE_NAMETABLE_ADDR, 1)
    set_tile_row_to_color_index_in_ppu(
        ppu=ppu,
        pattern_table_base=PATTERN_TABLE_0_ADDR,
        tile_id=1,
        row=0,
        color_index=0,
    )
    set_tile_row_to_color_index_in_ppu(
        ppu=ppu,
        pattern_table_base=PATTERN_TABLE_1_ADDR,
        tile_id=1,
        row=0,
        color_index=1,
    )

    mask = ppu_background_to_opaque_mask(ppu)

    assert mask[0] is True


def test_ppu_background_to_opaque_mask_matches_manual_extraction_and_pure_helper():
    """
    Objective:
    ppu_background_to_opaque_mask is an extraction/delegation helper, not a second
    opacity algorithm.
    """
    ppu = PPU()
    ppu.ppu_bus.write(BASE_NAMETABLE_ADDR + 2, 1)
    set_tile_row_to_color_index_in_ppu(
        ppu=ppu,
        pattern_table_base=PATTERN_TABLE_0_ADDR,
        tile_id=1,
        row=0,
        color_index=3,
    )

    extracted_nametable = read_bytes_from_ppu(ppu, BASE_NAMETABLE_ADDR, NAMETABLE_SIZE)
    extracted_pattern_table = read_bytes_from_ppu(
        ppu,
        PATTERN_TABLE_0_ADDR,
        PATTERN_TABLE_SIZE,
    )

    manual = build_background_opaque_mask(
        pattern_table=extracted_pattern_table,
        nametable=extracted_nametable,
    )
    from_ppu = ppu_background_to_opaque_mask(ppu)

    assert from_ppu == manual


def test_ppu_background_to_opaque_mask_does_not_need_attributes_or_palette_ram():
    """
    Objective:
    Opacity depends on CHR color index only, so this helper should be smaller than
    ppu_background_to_framebuffer().
    """
    source = inspect.getsource(ppu_background_to_opaque_mask)

    assert "BASE_ATTR_TABLE_ADDR" not in source
    assert "ATTR_TABLE_SIZE" not in source
    assert "PALETTE_RAM_ADDR" not in source
    assert "PALETTE_RAM_SIZE" not in source

Funciones de test (7)

test_ppu_background_to_opaque_mask_function_exists
test_ppu_background_to_opaque_mask_returns_one_entry_per_visible_pixel
test_ppu_background_to_opaque_mask_reads_visible_nametable_tile_ids
test_ppu_background_to_opaque_mask_uses_pattern_table_zero_when_background_bit_is_clear
test_ppu_background_to_opaque_mask_uses_pattern_table_one_when_background_bit_is_set
test_ppu_background_to_opaque_mask_matches_manual_extraction_and_pure_helper
test_ppu_background_to_opaque_mask_does_not_need_attributes_or_palette_ram