277. Nametable con la paleta de la NES

Renderizar un framebuffer de nametable usando la paleta RGB por defecto de la NES.

Lección 277 de 356 · tests/chapter_05_rendering_pipeline/test_277_nametable_with_nes_palette.py

Archivo a actualizar

emulator/rendering/nametable_renderer.py

Por qué existe este paso

El renderizador genérico de nametable admite paletas personalizadas

nametable_to_framebuffer(nametable_bytes, pattern_table_bytes, palette)

Eso es útil para tests y paletas de depuración. Ahora que tenemos NES_PALETTE_RGB, añadimos un ayudante de paleta por defecto:

nametable_to_nes_framebuffer(nametable_bytes, pattern_table_bytes)

Esto refleja el ayudante de tabla de patrones del paso de renderizado anterior.

Qué debería hacer

nametable_to_nes_framebuffer(nametable_bytes, pattern_table_bytes)
    -> nametable_to_framebuffer(
           nametable_bytes,
           pattern_table_bytes,
           NES_PALETTE_RGB,
       )

Ejemplo de implementación sugerida

from emulator.rendering.nes_palette import NES_PALETTE_RGB


def nametable_to_nes_framebuffer(
    nametable_bytes: bytes,
    pattern_table_bytes: bytes,
) -> Framebuffer:
    return nametable_to_framebuffer(
        nametable_bytes,
        pattern_table_bytes,
        NES_PALETTE_RGB,
    )

Simplificación importante

Esto todavía usa una única paleta compartida para cada tile. Aún no decodifica la tabla de atributos de 64 bytes, ni lee todavía la RAM de paletas de la PPU en $3F00-$3F1F. Esto es útil como renderizador simple/de depuración. Un renderizador posterior usará la tabla de atributos para elegir entre distintas paletas de fondo.

Regla importante de fixtures

Usa únicamente bytes de nametable/CHR sintéticos. No uses datos de ROM comercial en este test.

Fuera de alcance

selección de paleta mediante tabla de atributos
búsqueda en la RAM de paletas de la PPU
desplazamiento (scrolling)
sprites
OAMDMA
pantalla de pygame

Ejecutar esta lección

uv run pytest tests/chapter_05_rendering_pipeline/test_277_nametable_with_nes_palette.py -v

Implementación de ejemplo

Ejemplo de implementación sugerida

from emulator.rendering.nes_palette import NES_PALETTE_RGB


def nametable_to_nes_framebuffer(
    nametable_bytes: bytes,
    pattern_table_bytes: bytes,
) -> Framebuffer:
    return nametable_to_framebuffer(
        nametable_bytes,
        pattern_table_bytes,
        NES_PALETTE_RGB,
    )

Ver código del testtest_277_nametable_with_nes_palette.py

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE
from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.nametable_renderer import (
    NAMETABLE_SIZE,
    nametable_to_framebuffer,
    nametable_to_nes_framebuffer,
)
from emulator.rendering.nes_palette import NES_PALETTE_RGB


def make_empty_pattern_table() -> bytearray:
    """Create one synthetic 4096-byte pattern table."""
    return bytearray(PATTERN_TABLE_SIZE)


def make_empty_nametable() -> bytearray:
    """Create the visible 960-byte nametable tile-ID area."""
    return bytearray(NAMETABLE_SIZE)


def test_nametable_to_nes_framebuffer_function_exists():
    """
    Objective:
    Expose an explicit helper for rendering simplified nametable output using the
    default NES RGB palette approximation.
    """
    assert callable(nametable_to_nes_framebuffer)


def test_nametable_to_nes_framebuffer_returns_256_by_240_framebuffer():
    """
    Objective:
    The default-palette helper keeps the standard visible NES background size.
    """
    nametable = bytes(make_empty_nametable())
    pattern_table = bytes(make_empty_pattern_table())

    framebuffer = nametable_to_nes_framebuffer(nametable, pattern_table)

    assert isinstance(framebuffer, Framebuffer)
    assert framebuffer.width == 256
    assert framebuffer.height == 240
    assert len(framebuffer.pixels) == 256 * 240


def test_empty_nametable_and_empty_pattern_table_use_nes_palette_color_zero():
    """
    Objective:
    Empty CHR bytes decode to color index 0. With the default helper, that index
    should map to NES_PALETTE_RGB[0].
    """
    nametable = bytes(make_empty_nametable())
    pattern_table = bytes(make_empty_pattern_table())

    framebuffer = nametable_to_nes_framebuffer(nametable, pattern_table)

    assert framebuffer.get_pixel(0, 0) == NES_PALETTE_RGB[0]
    assert framebuffer.get_pixel(255, 239) == NES_PALETTE_RGB[0]


def test_synthetic_top_left_tile_color_index_three_uses_nes_palette_color_three():
    """
    Objective:
    A nametable tile that decodes to color index 3 should become NES_PALETTE_RGB[3]
    in the framebuffer.

    Setup:
        nametable[0] = 1, so tile #1 appears at the top-left background cell.

        tile #1 row 0:
            low bitplane  = 0xFF
            high bitplane = 0xFF

        Each pixel on row 0 decodes to binary 11, color index 3.
    """
    nametable = make_empty_nametable()
    nametable[0] = 1

    pattern_table = make_empty_pattern_table()
    tile_1_offset = 16
    pattern_table[tile_1_offset + 0] = 0xFF
    pattern_table[tile_1_offset + 8] = 0xFF

    framebuffer = nametable_to_nes_framebuffer(bytes(nametable), bytes(pattern_table))

    assert framebuffer.get_pixel(0, 0) == NES_PALETTE_RGB[3]
    assert framebuffer.get_pixel(7, 0) == NES_PALETTE_RGB[3]
    assert framebuffer.get_pixel(0, 1) == NES_PALETTE_RGB[0]


def test_nes_palette_helper_matches_generic_renderer_with_nes_palette():
    """
    Objective:
    nametable_to_nes_framebuffer is a convenience wrapper, not a separate rendering
    algorithm.

    It should produce the same framebuffer as:
        nametable_to_framebuffer(nametable, pattern_table, NES_PALETTE_RGB)
    """
    nametable = make_empty_nametable()
    nametable[1] = 2

    pattern_table = make_empty_pattern_table()
    tile_2_offset = 2 * 16
    pattern_table[tile_2_offset + 0] = 0b0101_0101
    pattern_table[tile_2_offset + 8] = 0b0011_0011

    generic = nametable_to_framebuffer(
        bytes(nametable),
        bytes(pattern_table),
        NES_PALETTE_RGB,
    )
    default_nes = nametable_to_nes_framebuffer(bytes(nametable), bytes(pattern_table))

    assert default_nes.width == generic.width
    assert default_nes.height == generic.height
    assert default_nes.pixels == generic.pixels

Funciones de test (5)

test_nametable_to_nes_framebuffer_function_exists
test_nametable_to_nes_framebuffer_returns_256_by_240_framebuffer
test_empty_nametable_and_empty_pattern_table_use_nes_palette_color_zero
test_synthetic_top_left_tile_color_index_three_uses_nes_palette_color_three
test_nes_palette_helper_matches_generic_renderer_with_nes_palette