272. Cuadrícula de índices de color a framebuffer

Convertir cuadrículas de índices de color en datos RGB de framebuffer.

Lección 272 de 356 · tests/chapter_05_rendering_pipeline/test_272_color_index_grid_to_framebuffer.py

Archivo a crear

emulator/rendering/color_index_renderer.py

Por qué existe este paso

Los ayudantes anteriores de PPU/CHR producen índices de color, no píxeles RGB. Por ejemplo, decode_chr_tile() produce valores como:

0, 1, 2, 3

Esos valores son índices de paleta. Todavía no son colores directamente visualizables.

Este paso crea un ayudante de renderizado puro que asigna

color-index grid + RGB palette -> Framebuffer

¿Qué es una cuadrícula de índices de color? Una cuadrícula de índices de color es una cuadrícula 2D donde cada número apunta a una paleta.

Ejemplo mínimo

grid = [
    [0, 1, 1, 0, ...],
    [2, 3, 3, 0, ...],
    ...
]

palette = [
    (0, 0, 0),
    (85, 85, 85),
    (170, 170, 170),
    (255, 255, 255),
]

Píxeles de framebuffer esperados

(x=0, y=0) -> palette[0] -> (0, 0, 0)
(x=1, y=0) -> palette[1] -> (85, 85, 85)
(x=0, y=1) -> palette[2] -> (170, 170, 170)
(x=1, y=1) -> palette[3] -> (255, 255, 255)

Ejemplo de implementación sugerida

from emulator.rendering.framebuffer import Framebuffer, RGBColor

Grid = list[list[int]]


def color_index_grid_to_framebuffer(
    grid: Grid,
    palette: list[RGBColor],
) -> Framebuffer:
    height = len(grid)
    width = len(grid[0])

    framebuffer = Framebuffer(width=width, height=height)

    for y, row in enumerate(grid):
        for x, color_index in enumerate(row):
            framebuffer.set_pixel(x, y, palette[color_index])

    return framebuffer

Simplificación importante

Por ahora, asume una entrada válida

grid is not empty
grid is rectangular
palette contains every used index
color indexes are valid

Se pueden añadir validaciones futuras más adelante si esto se convierte en un problema de depuración.

Regla de arquitectura

Este ayudante es una transformación de datos pura. No debería importar pygame, CPU, temporización de PPU, carga de ROM ni código de frontend.

Fuera de alcance

búsqueda en memoria de paleta de la NES
renderizado directo de tiles CHR
renderizado directo de tablas de patrones
renderizado de nametables/fondos
pantalla de pygame

Ejecutar esta lección

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

Implementación de ejemplo

Ejemplo mínimo

grid = [
    [0, 1, 1, 0, ...],
    [2, 3, 3, 0, ...],
    ...
]

palette = [
    (0, 0, 0),
    (85, 85, 85),
    (170, 170, 170),
    (255, 255, 255),
]

Ejemplo de implementación sugerida

from emulator.rendering.framebuffer import Framebuffer, RGBColor

Grid = list[list[int]]


def color_index_grid_to_framebuffer(
    grid: Grid,
    palette: list[RGBColor],
) -> Framebuffer:
    height = len(grid)
    width = len(grid[0])

    framebuffer = Framebuffer(width=width, height=height)

    for y, row in enumerate(grid):
        for x, color_index in enumerate(row):
            framebuffer.set_pixel(x, y, palette[color_index])

    return framebuffer

Ver código del testtest_272_color_index_grid_to_framebuffer.py

from pathlib import Path

from emulator.rendering.color_index_renderer import (
    Grid,
    color_index_grid_to_framebuffer,
)
from emulator.rendering.framebuffer import Framebuffer


def test_color_index_renderer_file_exists():
    """
    Objective:
    Keep color-index conversion separate from framebuffer storage.
    """
    assert Path("emulator/rendering/color_index_renderer.py").exists()


def test_color_index_renderer_declares_grid_alias_and_conversion_function():
    """
    Objective:
    Expose a small pure helper for converting indexed color grids to framebuffer
    data.
    """
    assert Grid == list[list[int]]
    assert callable(color_index_grid_to_framebuffer)


def test_color_index_grid_to_framebuffer_sets_output_dimensions_from_grid():
    """
    Objective:
    The framebuffer size should match the input grid dimensions.
    """
    grid = [
        [0, 0, 0],
        [0, 0, 0],
    ]
    palette = [(0, 0, 0)]

    framebuffer = color_index_grid_to_framebuffer(grid, palette)

    assert isinstance(framebuffer, Framebuffer)
    assert framebuffer.width == 3
    assert framebuffer.height == 2
    assert len(framebuffer.pixels) == 6


def test_color_index_grid_to_framebuffer_maps_2x2_indexes_to_rgb_pixels():
    """
    Objective:
    Convert a tiny 2x2 color-index grid into RGB framebuffer pixels.
    """
    grid = [
        [0, 1],
        [2, 3],
    ]
    palette = [
        (0, 0, 0),
        (85, 85, 85),
        (170, 170, 170),
        (255, 255, 255),
    ]

    framebuffer = color_index_grid_to_framebuffer(grid, palette)

    assert framebuffer.get_pixel(0, 0) == (0, 0, 0)
    assert framebuffer.get_pixel(1, 0) == (85, 85, 85)
    assert framebuffer.get_pixel(0, 1) == (170, 170, 170)
    assert framebuffer.get_pixel(1, 1) == (255, 255, 255)


def test_color_index_grid_to_framebuffer_preserves_flat_pixel_order():
    """
    Objective:
    The converted framebuffer should still use Framebuffer's flat row-major pixel
    order.

    Example:
        grid row 0 becomes pixels[0], pixels[1], pixels[2]
        grid row 1 becomes pixels[3], pixels[4], pixels[5]
    """
    grid = [
        [0, 1, 0],
        [1, 0, 1],
    ]
    palette = [
        (10, 10, 10),
        (200, 200, 200),
    ]

    framebuffer = color_index_grid_to_framebuffer(grid, palette)

    assert framebuffer.pixels == [
        (10, 10, 10),
        (200, 200, 200),
        (10, 10, 10),
        (200, 200, 200),
        (10, 10, 10),
        (200, 200, 200),
    ]


def test_color_index_grid_to_framebuffer_checkerboard_example():
    """
    Objective:
    Show a small pattern-like example that future CHR/pattern-table rendering can
    reuse conceptually.
    """
    dark = (0, 0, 0)
    light = (255, 255, 255)
    grid = [
        [0, 1, 0, 1],
        [1, 0, 1, 0],
        [0, 1, 0, 1],
        [1, 0, 1, 0],
    ]
    palette = [dark, light]

    framebuffer = color_index_grid_to_framebuffer(grid, palette)

    assert framebuffer.width == 4
    assert framebuffer.height == 4
    assert framebuffer.get_pixel(0, 0) == dark
    assert framebuffer.get_pixel(1, 0) == light
    assert framebuffer.get_pixel(0, 1) == light
    assert framebuffer.get_pixel(1, 1) == dark

Funciones de test (6)

test_color_index_renderer_file_exists
test_color_index_renderer_declares_grid_alias_and_conversion_function
test_color_index_grid_to_framebuffer_sets_output_dimensions_from_grid
test_color_index_grid_to_framebuffer_maps_2x2_indexes_to_rgb_pixels
test_color_index_grid_to_framebuffer_preserves_flat_pixel_order
test_color_index_grid_to_framebuffer_checkerboard_example