300. Декодирование записи спрайта

Декодирование одной записи спрайта из байтов OAM.

Урок 300 из 356 · tests/chapter_09_sprite_rendering/test_300_decode_sprite_entry.py

Файл для обновления

emulator/rendering/sprite_renderer.py

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

На предыдущем шаге был определён SpriteEntry. Теперь мы добавляем небольшой декодер, преобразующий сырые байты OAM PPU в один SpriteEntry.

Сырая раскладка OAM

sprite 0 -> bytes 0, 1, 2, 3
sprite 1 -> bytes 4, 5, 6, 7
...
sprite 63 -> bytes 252, 253, 254, 255

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

def decode_sprite_entry(oam: bytes | bytearray, sprite_index: int) -> SpriteEntry:
    if len(oam) < OAM_SIZE:
        raise ValueError("OAM must contain 256 bytes")

    if not 0 <= sprite_index < OAM_SPRITE_COUNT:
        raise ValueError("sprite_index must be in range 0..63")

    base = sprite_index * BYTES_PER_SPRITE

    return SpriteEntry(
        y=oam[base],
        tile_index=oam[base + 1],
        attributes=oam[base + 2],
        x=oam[base + 3],
    )

Важная деталь NES

Сырой байт Y имеет особую семантику рендеринга на реальном железе. Спрайты отображаются на одну строку развёртки ниже сохранённого значения Y. Не корректируйте его в этом декодере. Эта функция возвращает только сырые данные OAM.

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

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

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

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

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

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

def decode_sprite_entry(oam: bytes | bytearray, sprite_index: int) -> SpriteEntry:
    if len(oam) < OAM_SIZE:
        raise ValueError("OAM must contain 256 bytes")

    if not 0 <= sprite_index < OAM_SPRITE_COUNT:
        raise ValueError("sprite_index must be in range 0..63")

    base = sprite_index * BYTES_PER_SPRITE

    return SpriteEntry(
        y=oam[base],
        tile_index=oam[base + 1],
        attributes=oam[base + 2],
        x=oam[base + 3],
    )

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

import pytest

from emulator.rendering.sprite_renderer import SpriteEntry, decode_sprite_entry


def test_decode_sprite_entry_reads_sprite_zero_bytes_in_oam_order():
    """
    Objective:
    Sprite index 0 reads OAM bytes 0..3 as y, tile_index, attributes, x.
    """
    oam = bytearray(256)
    oam[0:4] = bytes([12, 34, 0b1010_0001, 56])

    entry = decode_sprite_entry(oam, 0)

    assert entry == SpriteEntry(
        y=12,
        tile_index=34,
        attributes=0b1010_0001,
        x=56,
    )


def test_decode_sprite_entry_reads_sprite_one_from_next_four_bytes():
    """
    Objective:
    Sprite index 1 starts at byte 4, not byte 1.
    """
    oam = bytearray(256)
    oam[4:8] = bytes([20, 21, 22, 23])

    entry = decode_sprite_entry(oam, 1)

    assert entry == SpriteEntry(y=20, tile_index=21, attributes=22, x=23)


def test_decode_sprite_entry_reads_last_valid_sprite():
    """
    Objective:
    Sprite index 63 is the last valid sprite and reads bytes 252..255.
    """
    oam = bytearray(256)
    oam[252:256] = bytes([1, 2, 3, 4])

    entry = decode_sprite_entry(oam, 63)

    assert entry == SpriteEntry(y=1, tile_index=2, attributes=3, x=4)


def test_decode_sprite_entry_accepts_immutable_bytes_as_oam_source():
    """
    Objective:
    The decoder can read from bytes or bytearray because it only observes OAM data.
    """
    oam = bytearray(256)
    oam[8:12] = bytes([7, 8, 9, 10])

    entry = decode_sprite_entry(bytes(oam), 2)

    assert entry == SpriteEntry(y=7, tile_index=8, attributes=9, x=10)


def test_decode_sprite_entry_rejects_short_oam():
    """
    Objective:
    The decoder should fail clearly if it is not given a full 256-byte OAM buffer.
    """
    with pytest.raises(ValueError, match="OAM must contain 256 bytes"):
        decode_sprite_entry(bytearray(255), 0)


def test_decode_sprite_entry_rejects_invalid_sprite_indexes():
    """
    Objective:
    Valid sprite indexes are 0 through 63 inclusive.
    """
    oam = bytearray(256)

    with pytest.raises(ValueError, match="sprite_index must be in range 0..63"):
        decode_sprite_entry(oam, -1)

    with pytest.raises(ValueError, match="sprite_index must be in range 0..63"):
        decode_sprite_entry(oam, 64)

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

test_decode_sprite_entry_reads_sprite_zero_bytes_in_oam_order
test_decode_sprite_entry_reads_sprite_one_from_next_four_bytes
test_decode_sprite_entry_reads_last_valid_sprite
test_decode_sprite_entry_accepts_immutable_bytes_as_oam_source
test_decode_sprite_entry_rejects_short_oam
test_decode_sprite_entry_rejects_invalid_sprite_indexes