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()
精灵属性位解码
精灵调色板
渲染像素
精灵 0 命中
精灵溢出
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