270. Forma de datos del framebuffer

Crear la forma de datos pura del framebuffer para el pipeline de renderizado.

Lección 270 de 356 · tests/chapter_05_rendering_pipeline/test_270_framebuffer_data_shape.py

Archivos a crear

emulator/rendering/
emulator/rendering/framebuffer.py

Por qué existe este paso

La fase 7 comienza definiendo la forma de datos que el núcleo del emulador producirá para la salida visual. Esto debe ser datos puros de Python, no datos específicos de pygame.

¿Qué es un framebuffer? Un framebuffer es un bloque de datos de píxeles que representa una imagen/fotograma completo.

Ejemplo mínimo

A 256x240 NES framebuffer contains:

    256 * 240 = 61440 pixels

Cada píxel se representa como una tupla RGB

    (red, green, blue)

Ejemplo

    BLACK = (0, 0, 0)
    WHITE = (255, 255, 255)

Concepto erróneo común

Framebuffer no significa ventana de pygame. El framebuffer son datos del núcleo del emulador. Pygame puede mostrarlo después, pero pygame no debería ser necesario para crear o probar el framebuffer.

Ejemplo de implementación sugerido

from dataclasses import dataclass, field

RGBColor = tuple[int, int, int]

NES_SCREEN_WIDTH = 256
NES_SCREEN_HEIGHT = 240
BLACK: RGBColor = (0, 0, 0)


@dataclass
class Framebuffer:
    width: int = NES_SCREEN_WIDTH
    height: int = NES_SCREEN_HEIGHT
    pixels: list[RGBColor] = field(default_factory=list)

    def __post_init__(self) -> None:
        if not self.pixels:
            self.pixels = [BLACK] * (self.width * self.height)

        if len(self.pixels) != self.width * self.height:
            raise ValueError("Framebuffer pixel count must be equal width * height")

Invariante importante

Después de la construcción

len(framebuffer.pixels) == framebuffer.width * framebuffer.height

Fuera de alcance

métodos get_pixel/set_pixel, probados en el siguiente paso
validación de coordenadas
validación de componentes RGB
conversión de índices de paleta NES a RGB
renderizado de datos CHR/nametable
visualización en pygame/frontend

Ejecutar esta lección

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

Implementación de ejemplo

Ejemplo de implementación sugerido

from dataclasses import dataclass, field

RGBColor = tuple[int, int, int]

NES_SCREEN_WIDTH = 256
NES_SCREEN_HEIGHT = 240
BLACK: RGBColor = (0, 0, 0)


@dataclass
class Framebuffer:
    width: int = NES_SCREEN_WIDTH
    height: int = NES_SCREEN_HEIGHT
    pixels: list[RGBColor] = field(default_factory=list)

    def __post_init__(self) -> None:
        if not self.pixels:
            self.pixels = [BLACK] * (self.width * self.height)

        if len(self.pixels) != self.width * self.height:
            raise ValueError("Framebuffer pixel count must be equal width * height")

Ver código del testtest_270_framebuffer_data_shape.py

from dataclasses import is_dataclass
from pathlib import Path

import pytest

from emulator.rendering.framebuffer import (
    BLACK,
    NES_SCREEN_HEIGHT,
    NES_SCREEN_WIDTH,
    Framebuffer,
)


def test_rendering_folder_and_framebuffer_file_exist():
    """
    Objective:
    Start a rendering module for pure rendering data and transformations.
    """
    assert Path("emulator/rendering").exists()
    assert Path("emulator/rendering/framebuffer.py").exists()


def test_framebuffer_constants_define_nes_screen_size_and_black_color():
    """
    Objective:
    Name the standard NES visible framebuffer dimensions and default clear color.
    """
    assert NES_SCREEN_WIDTH == 256
    assert NES_SCREEN_HEIGHT == 240
    assert BLACK == (0, 0, 0)


def test_framebuffer_is_dataclass_with_expected_fields():
    """
    Objective:
    Framebuffer is a small data container with width, height, and flat pixel data.
    """
    assert is_dataclass(Framebuffer)
    assert list(Framebuffer.__dataclass_fields__) == ["width", "height", "pixels"]


def test_framebuffer_default_init_creates_blank_nes_sized_frame():
    """
    Objective:
    Framebuffer() creates a blank 256x240 frame by default.
    """
    framebuffer = Framebuffer()

    assert framebuffer.width == NES_SCREEN_WIDTH
    assert framebuffer.height == NES_SCREEN_HEIGHT
    assert len(framebuffer.pixels) == NES_SCREEN_WIDTH * NES_SCREEN_HEIGHT
    assert framebuffer.pixels[0] == BLACK
    assert framebuffer.pixels[-1] == BLACK


def test_framebuffer_custom_size_initializes_blank_pixels():
    """
    Objective:
    The same data shape can be used for small tests without allocating a full NES
    frame.
    """
    framebuffer = Framebuffer(width=4, height=3)

    assert framebuffer.width == 4
    assert framebuffer.height == 3
    assert framebuffer.pixels == [BLACK] * 12


def test_framebuffer_accepts_existing_pixel_data_when_size_matches():
    """
    Objective:
    Framebuffer can wrap existing pixel data as long as the pixel count matches
    width * height.
    """
    pixels = [
        (255, 0, 0),
        (0, 255, 0),
        (0, 0, 255),
        (255, 255, 255),
    ]

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

    assert framebuffer.pixels == pixels


def test_framebuffer_rejects_existing_pixel_data_with_wrong_size():
    """
    Objective:
    Protect the core framebuffer invariant: pixel count must equal width * height.
    """
    with pytest.raises(ValueError, match="Framebuffer pixel count"):
        Framebuffer(width=2, height=2, pixels=[BLACK])

Funciones de test (7)

test_rendering_folder_and_framebuffer_file_exist
test_framebuffer_constants_define_nes_screen_size_and_black_color
test_framebuffer_is_dataclass_with_expected_fields
test_framebuffer_default_init_creates_blank_nes_sized_frame
test_framebuffer_custom_size_initializes_blank_pixels
test_framebuffer_accepts_existing_pixel_data_when_size_matches
test_framebuffer_rejects_existing_pixel_data_with_wrong_size