301. Определение атрибутов спрайта

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

Урок 301 из 356 · tests/chapter_09_sprite_rendering/test_301_sprite_attribute_definition.py

Изменяемый файл

emulator/rendering/sprite_renderer.py

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

Каждая запись SpriteEntry содержит один исходный байт атрибутов. Прежде чем отрисовывать спрайты, нам нужны имена для значимых битов и небольшой dataclass для декодированного значения.

Байт атрибутов спрайта NES

bits 0-1: sprite palette ID
bits 2-4: unused / ignored for now
bit 5: priority behind background
bit 6: horizontal flip
bit 7: vertical flip

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

SPRITE_PALETTE_ID_MASK = 0b0000_0011
SPRITE_IS_BEHIND_BACKGROUND = 1 << 5
SPRITE_FLIP_HORIZONTAL = 1 << 6
SPRITE_FLIP_VERTICAL = 1 << 7


@dataclass(frozen=True)
class SpriteAttributes:
    palette_id: int
    is_behind_background: bool
    flip_horizontal: bool
    flip_vertical: bool

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

"Sprite attributes are the same as background attribute table bytes."

Нет. Байты таблицы атрибутов фона выбирают палитры фона для областей тайлов. Атрибуты спрайта задаются для каждого спрайта отдельно и находятся в байте 2 OAM.

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

decode_sprite_attributes()
вспомогательная функция для палитровой RAM спрайтов
отрисовка пикселей
попадание спрайта 0
переполнение спрайтов
pygame

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

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

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

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

SPRITE_PALETTE_ID_MASK = 0b0000_0011
SPRITE_IS_BEHIND_BACKGROUND = 1 << 5
SPRITE_FLIP_HORIZONTAL = 1 << 6
SPRITE_FLIP_VERTICAL = 1 << 7


@dataclass(frozen=True)
class SpriteAttributes:
    palette_id: int
    is_behind_background: bool
    flip_horizontal: bool
    flip_vertical: bool

Показать код тестаtest_301_sprite_attribute_definition.py

from dataclasses import is_dataclass
from pathlib import Path

from emulator.rendering.sprite_renderer import (
    SPRITE_FLIP_HORIZONTAL,
    SPRITE_FLIP_VERTICAL,
    SPRITE_IS_BEHIND_BACKGROUND,
    SPRITE_PALETTE_ID_MASK,
    SpriteAttributes,
)


def test_sprite_attribute_constants_define_relevant_oam_bits():
    """
    Objective:
    Constants document the meaning of the relevant bits in OAM attribute byte 2.
    """
    assert SPRITE_PALETTE_ID_MASK == 0b0000_0011
    assert SPRITE_IS_BEHIND_BACKGROUND == 1 << 5
    assert SPRITE_FLIP_HORIZONTAL == 1 << 6
    assert SPRITE_FLIP_VERTICAL == 1 << 7


def test_sprite_attributes_is_frozen_dataclass():
    """
    Objective:
    SpriteAttributes is a small immutable snapshot of decoded attribute meaning.
    """
    assert is_dataclass(SpriteAttributes)

    attributes = SpriteAttributes(
        palette_id=2,
        is_behind_background=True,
        flip_horizontal=True,
        flip_vertical=False,
    )

    assert attributes.palette_id == 2
    assert attributes.is_behind_background is True
    assert attributes.flip_horizontal is True
    assert attributes.flip_vertical is False


def test_sprite_attributes_field_order_is_teaching_friendly():
    """
    Objective:
    Field order follows the common reading order: palette, priority, flips.
    """
    assert list(SpriteAttributes.__dataclass_fields__) == [
        "palette_id",
        "is_behind_background",
        "flip_horizontal",
        "flip_vertical",
    ]


def test_sprite_attribute_definition_does_not_import_pygame():
    """
    Objective:
    Sprite attribute decoding must stay free of frontend dependencies.

    Historical note:
    Later sprite rendering steps intentionally import Framebuffer in this module to
    draw pure framebuffer data. That is acceptable. pygame is still not allowed.
    """
    source = Path("emulator/rendering/sprite_renderer.py").read_text()

    assert "import pygame" not in source

Тестовые функции (4)

test_sprite_attribute_constants_define_relevant_oam_bits
test_sprite_attributes_is_frozen_dataclass
test_sprite_attributes_field_order_is_teaching_friendly
test_sprite_attribute_definition_does_not_import_pygame