302. 解码精灵属性

解码一个原始精灵属性字节。

第 302 / 356 · tests/chapter_09_sprite_rendering/test_302_decode_sprite_attributes.py

需要更新的文件

emulator/rendering/sprite_renderer.py

为什么需要这一步

上一步定义了 SpriteAttributes。现在我们要把原始的 OAM 属性字节转换成这个解码后的结构体。

建议的实现示例

def decode_sprite_attributes(attributes: int) -> SpriteAttributes:
    attributes &= 0xFF

    return SpriteAttributes(
        palette_id=attributes & SPRITE_PALETTE_ID_MASK,
        is_behind_background=(attributes & SPRITE_IS_BEHIND_BACKGROUND) != 0,
        flip_horizontal=(attributes & SPRITE_FLIP_HORIZONTAL) != 0,
        flip_vertical=(attributes & SPRITE_FLIP_VERTICAL) != 0,
    )

示例

attributes = 0b1110_0011

含义

palette_id = 3
is_behind_background = True
flip_horizontal = True
flip_vertical = True

第 2-4 位

目前忽略。即使它们被置位,也不要抛出异常。

本步骤不涉及的内容

精灵调色板 RAM 辅助函数
渲染像素
sprite 0 hit
sprite overflow
pygame

运行本课

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

示例实现

建议的实现示例

def decode_sprite_attributes(attributes: int) -> SpriteAttributes:
    attributes &= 0xFF

    return SpriteAttributes(
        palette_id=attributes & SPRITE_PALETTE_ID_MASK,
        is_behind_background=(attributes & SPRITE_IS_BEHIND_BACKGROUND) != 0,
        flip_horizontal=(attributes & SPRITE_FLIP_HORIZONTAL) != 0,
        flip_vertical=(attributes & SPRITE_FLIP_VERTICAL) != 0,
    )

含义

palette_id = 3
is_behind_background = True
flip_horizontal = True
flip_vertical = True

查看测试代码test_302_decode_sprite_attributes.py

from emulator.rendering.sprite_renderer import SpriteAttributes, decode_sprite_attributes


def test_decode_sprite_attributes_extracts_palette_id_0_to_3():
    """
    Objective:
    Bits 0-1 select one of four sprite palettes.
    """
    assert decode_sprite_attributes(0b0000_0000).palette_id == 0
    assert decode_sprite_attributes(0b0000_0001).palette_id == 1
    assert decode_sprite_attributes(0b0000_0010).palette_id == 2
    assert decode_sprite_attributes(0b0000_0011).palette_id == 3


def test_decode_sprite_attributes_detects_priority_behind_background_bit():
    """
    Objective:
    Bit 5 marks the sprite as behind background pixels for later compositing.
    """
    assert decode_sprite_attributes(0b0000_0000).is_behind_background is False
    assert decode_sprite_attributes(0b0010_0000).is_behind_background is True


def test_decode_sprite_attributes_detects_horizontal_and_vertical_flip_bits():
    """
    Objective:
    Bit 6 controls horizontal flip and bit 7 controls vertical flip.
    """
    no_flip = decode_sprite_attributes(0b0000_0000)
    horizontal = decode_sprite_attributes(0b0100_0000)
    vertical = decode_sprite_attributes(0b1000_0000)
    both = decode_sprite_attributes(0b1100_0000)

    assert no_flip.flip_horizontal is False
    assert no_flip.flip_vertical is False

    assert horizontal.flip_horizontal is True
    assert horizontal.flip_vertical is False

    assert vertical.flip_horizontal is False
    assert vertical.flip_vertical is True

    assert both.flip_horizontal is True
    assert both.flip_vertical is True


def test_decode_sprite_attributes_decodes_all_relevant_bits_together():
    """
    Objective:
    A realistic attribute byte can combine palette, priority, and flip bits.
    """
    decoded = decode_sprite_attributes(0b1110_0011)

    assert decoded == SpriteAttributes(
        palette_id=3,
        is_behind_background=True,
        flip_horizontal=True,
        flip_vertical=True,
    )


def test_decode_sprite_attributes_ignores_bits_2_to_4():
    """
    Objective:
    Bits 2-4 are ignored for now. They should not affect decoded fields.
    """
    decoded = decode_sprite_attributes(0b0001_1100)

    assert decoded == SpriteAttributes(
        palette_id=0,
        is_behind_background=False,
        flip_horizontal=False,
        flip_vertical=False,
    )


def test_decode_sprite_attributes_masks_input_to_one_byte():
    """
    Objective:
    The decoder treats input as an 8-bit hardware register value.
    """
    decoded = decode_sprite_attributes(0x1C3)

    assert decoded == decode_sprite_attributes(0xC3)

测试函数 (6)

test_decode_sprite_attributes_extracts_palette_id_0_to_3
test_decode_sprite_attributes_detects_priority_behind_background_bit
test_decode_sprite_attributes_detects_horizontal_and_vertical_flip_bits
test_decode_sprite_attributes_decodes_all_relevant_bits_together
test_decode_sprite_attributes_ignores_bits_2_to_4
test_decode_sprite_attributes_masks_input_to_one_byte