299. Definición de la entrada de sprite

Definir el modelo de datos básico de una entrada de sprite en OAM.

Lección 299 de 356 · tests/chapter_09_sprite_rendering/test_299_sprite_entry_definition.py

Archivo a crear

emulator/rendering/sprite_renderer.py

Por qué existe este paso

OAMDMA ya copia 256 bytes en PPU.oam. Antes de renderizar sprites, necesitamos un pequeño modelo de datos para una entrada de sprite.

¿Qué es OAM? OAM significa Object Attribute Memory. Es la memoria interna de sprites de la PPU:

64 sprites * 4 bytes = 256 bytes

Cada entrada de sprite usa cuatro bytes

byte 0: Y position
byte 1: tile index
byte 2: attributes
byte 3: X position

Este primer paso de renderizado de sprites solo crea las constantes y la dataclass SpriteEntry. Todavía no decodifica desde OAM ni renderiza píxeles.

Ejemplo de implementación sugerido

from dataclasses import dataclass


OAM_SPRITE_COUNT = 64
BYTES_PER_SPRITE = 4
OAM_SIZE = OAM_SPRITE_COUNT * BYTES_PER_SPRITE


@dataclass(frozen=True)
class SpriteEntry:
    y: int
    tile_index: int
    attributes: int
    x: int

Concepto erróneo habitual

"OAMDMA means sprites are visible."

No. OAMDMA solo rellena PPU.oam. Renderizar esas entradas como píxeles es un paso posterior del capítulo 09.

Fuera de alcance

decode_sprite_entry()
Decodificación de bits de atributos de sprite
Paletas de sprites
Renderizado de píxeles
Sprite 0 hit
Desbordamiento de sprites
pygame

Ejecutar esta lección

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

Implementación de ejemplo

Ejemplo de implementación sugerido

from dataclasses import dataclass


OAM_SPRITE_COUNT = 64
BYTES_PER_SPRITE = 4
OAM_SIZE = OAM_SPRITE_COUNT * BYTES_PER_SPRITE


@dataclass(frozen=True)
class SpriteEntry:
    y: int
    tile_index: int
    attributes: int
    x: int

Ver código del testtest_299_sprite_entry_definition.py

from dataclasses import is_dataclass
from pathlib import Path

from emulator.rendering.sprite_renderer import (
    BYTES_PER_SPRITE,
    OAM_SIZE,
    OAM_SPRITE_COUNT,
    SpriteEntry,
)


def test_sprite_renderer_file_exists():
    """
    Objective:
    Sprite rendering starts in a pure emulator rendering module.
    """
    assert Path("emulator/rendering/sprite_renderer.py").exists()


def test_oam_sprite_constants_define_standard_nes_oam_layout():
    """
    Objective:
    Constants document the standard NES sprite memory shape.
    """
    assert OAM_SPRITE_COUNT == 64
    assert BYTES_PER_SPRITE == 4
    assert OAM_SIZE == 256
    assert OAM_SIZE == OAM_SPRITE_COUNT * BYTES_PER_SPRITE


def test_sprite_entry_is_frozen_dataclass_snapshot():
    """
    Objective:
    SpriteEntry is a small immutable snapshot of four OAM bytes.
    """
    assert is_dataclass(SpriteEntry)

    entry = SpriteEntry(y=10, tile_index=20, attributes=30, x=40)

    assert entry.y == 10
    assert entry.tile_index == 20
    assert entry.attributes == 30
    assert entry.x == 40


def test_sprite_entry_field_order_matches_oam_byte_order():
    """
    Objective:
    The dataclass field order should match the raw OAM byte order:

        y, tile_index, attributes, x
    """
    assert list(SpriteEntry.__dataclass_fields__) == [
        "y",
        "tile_index",
        "attributes",
        "x",
    ]


def test_sprite_entry_definition_does_not_import_pygame():
    """
    Objective:
    The sprite renderer must stay free of frontend dependencies.

    Historical note:
    This test originally also checked that Framebuffer was not imported because the
    first sprite step was data-only. Later steps intentionally render one sprite
    into a pure Framebuffer, so Framebuffer is now allowed. pygame is still not
    allowed.
    """
    source = Path("emulator/rendering/sprite_renderer.py").read_text()

    assert "import pygame" not in source

Funciones de test (5)

test_sprite_renderer_file_exists
test_oam_sprite_constants_define_standard_nes_oam_layout
test_sprite_entry_is_frozen_dataclass_snapshot
test_sprite_entry_field_order_matches_oam_byte_order
test_sprite_entry_definition_does_not_import_pygame