275. Tabla de patrones con la paleta de la NES

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

Lección 275 de 356 · tests/chapter_05_rendering_pipeline/test_275_pattern_table_with_nes_palette.py

Archivo a actualizar

emulator/rendering/pattern_table_renderer.py

Por qué existe este paso

El renderizador genérico de tabla de patrones ya admite paletas personalizadas

pattern_table_to_framebuffer(pattern_table_bytes, palette)

Eso es útil para tests y paletas de depuración. Ahora que tenemos una aproximación de paleta RGB por defecto de la NES, añadimos un ayudante de conveniencia:

pattern_table_to_nes_framebuffer(pattern_table_bytes)

Este ayudante mantiene explícita la ruta de paleta por defecto sin eliminar el soporte de paletas personalizadas.

Qué debería hacer

pattern_table_to_nes_framebuffer(pattern_table_bytes)
    -> pattern_table_to_framebuffer(pattern_table_bytes, NES_PALETTE_RGB)

Ejemplo de implementación sugerida

from emulator.rendering.nes_palette import NES_PALETTE_RGB


def pattern_table_to_nes_framebuffer(
    pattern_table_bytes: bytes,
) -> Framebuffer:
    return pattern_table_to_framebuffer(pattern_table_bytes, NES_PALETTE_RGB)

¿Por qué no hacer que NES_PALETTE_RGB sea el argumento por defecto?

Esto funcionaría

def pattern_table_to_framebuffer(pattern_table_bytes, palette=NES_PALETTE_RGB):
    ...

Pero un ayudante separado es más claro para el tutorial

pattern_table_to_framebuffer(..., palette)
    custom palette path

pattern_table_to_nes_framebuffer(...)
    default NES palette path

Nota: Este test usa únicamente bytes CHR sintéticos. No uses datos CHR de una ROM comercial en este test.

Fuera de alcance

pantalla de pygame
escritura de archivos de imagen
renderizado de nametable/fondo
búsqueda en la RAM de paletas de la PPU
colores de énfasis de PPUMASK
sprites

Ejecutar esta lección

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

Implementación de ejemplo

Ejemplo de implementación sugerida

from emulator.rendering.nes_palette import NES_PALETTE_RGB


def pattern_table_to_nes_framebuffer(
    pattern_table_bytes: bytes,
) -> Framebuffer:
    return pattern_table_to_framebuffer(pattern_table_bytes, NES_PALETTE_RGB)

Ver código del testtest_275_pattern_table_with_nes_palette.py

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE
from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.nes_palette import NES_PALETTE_RGB
from emulator.rendering.pattern_table_renderer import (
    pattern_table_to_framebuffer,
    pattern_table_to_nes_framebuffer,
)


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


def test_pattern_table_to_nes_framebuffer_function_exists():
    """
    Objective:
    Expose an explicit helper for rendering pattern-table debug output using the
    default NES RGB palette approximation.
    """
    assert callable(pattern_table_to_nes_framebuffer)


def test_pattern_table_to_nes_framebuffer_returns_128_by_128_framebuffer():
    """
    Objective:
    The default-palette helper keeps the same pattern-table debug dimensions.
    """
    pattern_table = bytes(make_empty_pattern_table())

    framebuffer = pattern_table_to_nes_framebuffer(pattern_table)

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


def test_empty_pattern_table_uses_nes_palette_color_zero():
    """
    Objective:
    Empty CHR bytes decode to color index 0, so every framebuffer pixel should use
    NES_PALETTE_RGB[0].
    """
    pattern_table = bytes(make_empty_pattern_table())

    framebuffer = pattern_table_to_nes_framebuffer(pattern_table)

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


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

    CHR tile encoding:
        low bitplane byte  = 0xFF
        high bitplane byte = 0xFF

    For each pixel:
        low bit  = 1
        high bit = 1
        color index = binary 11 = 3
    """
    pattern_table = make_empty_pattern_table()

    # First tile, row 0 only: all pixels become color index 3.
    pattern_table[0] = 0xFF
    pattern_table[8] = 0xFF

    framebuffer = pattern_table_to_nes_framebuffer(bytes(pattern_table))

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

    # Row 1 was left as zero bytes, so it still maps to color index 0.
    assert framebuffer.get_pixel(0, 1) == NES_PALETTE_RGB[0]


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

    It should produce the same pixels as:
        pattern_table_to_framebuffer(pattern_table, NES_PALETTE_RGB)
    """
    pattern_table = make_empty_pattern_table()

    # First tile, row 0: repeating 0, 1, 2, 3 pattern.
    pattern_table[0] = 0b0101_0101
    pattern_table[8] = 0b0011_0011

    generic = pattern_table_to_framebuffer(bytes(pattern_table), NES_PALETTE_RGB)
    default_nes = pattern_table_to_nes_framebuffer(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_pattern_table_to_nes_framebuffer_function_exists
test_pattern_table_to_nes_framebuffer_returns_128_by_128_framebuffer
test_empty_pattern_table_uses_nes_palette_color_zero
test_synthetic_tile_color_index_three_uses_nes_palette_color_three
test_nes_palette_helper_matches_generic_renderer_with_nes_palette