299. Определение записи спрайта

Определение базовой модели данных записи спрайта OAM.

Урок 299 из 356 · tests/chapter_09_sprite_rendering/test_299_sprite_entry_definition.py

Файл для создания

emulator/rendering/sprite_renderer.py

Зачем нужен этот шаг

OAMDMA уже копирует 256 байт в PPU.oam. Прежде чем рендерить спрайты, нужна небольшая модель данных для одной записи спрайта.

Что такое OAM? OAM означает Object Attribute Memory. Это внутренняя память спрайтов PPU:

64 sprites * 4 bytes = 256 bytes

Каждая запись спрайта занимает четыре байта

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

Этот первый шаг рендеринга спрайтов только создаёт константы и датакласс SpriteEntry. Он ещё не декодирует данные из OAM и не рендерит пиксели.

Пример предполагаемой реализации

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

Распространённое заблуждение

"OAMDMA means sprites are visible."

Нет. OAMDMA лишь заполняет PPU.oam. Рендеринг этих записей в пиксели — это более поздний шаг главы 09.

Вне рамок этого шага

decode_sprite_entry()
декодирование битов атрибутов спрайта
палитры спрайтов
рендеринг пикселей
sprite 0 hit
переполнение спрайтов
pygame

Запустить этот урок

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

Пример реализации

Пример предполагаемой реализации

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

Показать код тестаtest_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

Тестовые функции (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