278. Выбор палитры по таблице атрибутов

Декодирование выбора фоновой палитры из таблицы атрибутов таблицы имён.

Урок 278 из 356 · tests/chapter_05_rendering_pipeline/test_278_attribute_table_palette_selection.py

Справочная информация

https://www.nesdev.org/wiki/PPU_attribute_tables

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

emulator/rendering/attribute_table.py

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

Текущий рендерер таблицы имён использует одну общую 4-цветную палитру для каждого тайла. Настоящие фоны NES выбирают между четырьмя фоновыми субпалитрами с помощью таблицы атрибутов таблицы имён.

Этот шаг пока не выполняет рендеринг с атрибутами. Он отвечает лишь на один небольшой вопрос:

For tile coordinate (tile_x, tile_y), which palette ID does the attribute
table select?

Что такое таблица атрибутов?

У каждой таблицы имён есть

960 bytes tile IDs
64 bytes attribute table

Таблица атрибутов — это сетка байтов размером 8x8. Каждый байт атрибута покрывает область 4x4 тайла, то есть 32x32 пикселя.

Один байт атрибута разбит на четыре квадранта размером 2x2 тайла

+-----------------------+
| top-left | top-right  |
|  2x2     |   2x2      |
+----------+------------+
| bottom-l | bottom-r   |
|  2x2     |   2x2      |
+-----------------------+

Каждый квадрант хранит 2-битный идентификатор палитры

0b00 -> palette 0
0b01 -> palette 1
0b10 -> palette 2
0b11 -> palette 3

Важное различие

Таблица атрибутов не хранит RGB-цвета и не хранит индексы цвета NES. Она выбирает, какую фоновую субпалитру использовать. Позже палитровая RAM и RGB-палитра NES превратят этот выбор в реальные цвета.

Расположение битов внутри одного байта атрибута

bits 0-1 -> top-left quadrant
bits 2-3 -> top-right quadrant
bits 4-5 -> bottom-left quadrant
bits 6-7 -> bottom-right quadrant

Этот шаг реализует: распаковку/чтение одного квадранта из байта.

Пример читаемой реализации

TABLE_SIZE = 64
BYTES_PER_ROW = 8


def get_attribute_palette_id(
    attribute_table: bytes,
    tile_x: int,
    tile_y: int,
) -> int:
    if len(attribute_table) != TABLE_SIZE:
        raise ValueError("Attribute table must be 64 bytes")

    attribute_x = tile_x // 4
    attribute_y = tile_y // 4
    attribute_index = attribute_y * BYTES_PER_ROW + attribute_x
    attribute_byte = attribute_table[attribute_index]

    quadrant_x = (tile_x % 4) // 2
    quadrant_y = (tile_y % 4) // 2

    is_top_left = quadrant_x == 0 and quadrant_y == 0
    is_top_right = quadrant_x == 1 and quadrant_y == 0
    is_bottom_left = quadrant_x == 0 and quadrant_y == 1

    if is_top_left:
        return attribute_byte & 0b11

    if is_top_right:
        return (attribute_byte >> 2) & 0b11

    if is_bottom_left:
        return (attribute_byte >> 4) & 0b11

    return (attribute_byte >> 6) & 0b11

Почему tile_x // 4 и tile_y // 4? Потому что каждый байт атрибута покрывает область 4x4 тайла.

Почему (tile_x % 4) // 2?

Внутри этой области 4x4

tile positions 0,1 belong to quadrant 0
tile positions 2,3 belong to quadrant 1

Таким образом

0 % 4 // 2 -> 0
1 % 4 // 2 -> 0
2 % 4 // 2 -> 1
3 % 4 // 2 -> 1

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

рендеринг таблиц имён с атрибутами
поиск в палитровой RAM PPU
преобразование в RGB-палитру
скроллинг
спрайты
отображение через pygame

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

uv run pytest tests/chapter_05_rendering_pipeline/test_278_attribute_table_palette_selection.py -v

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

Пример читаемой реализации

TABLE_SIZE = 64
BYTES_PER_ROW = 8


def get_attribute_palette_id(
    attribute_table: bytes,
    tile_x: int,
    tile_y: int,
) -> int:
    if len(attribute_table) != TABLE_SIZE:
        raise ValueError("Attribute table must be 64 bytes")

    attribute_x = tile_x // 4
    attribute_y = tile_y // 4
    attribute_index = attribute_y * BYTES_PER_ROW + attribute_x
    attribute_byte = attribute_table[attribute_index]

    quadrant_x = (tile_x % 4) // 2
    quadrant_y = (tile_y % 4) // 2

    is_top_left = quadrant_x == 0 and quadrant_y == 0
    is_top_right = quadrant_x == 1 and quadrant_y == 0
    is_bottom_left = quadrant_x == 0 and quadrant_y == 1

    if is_top_left:
        return attribute_byte & 0b11

    if is_top_right:
        return (attribute_byte >> 2) & 0b11

    if is_bottom_left:
        return (attribute_byte >> 4) & 0b11

    return (attribute_byte >> 6) & 0b11

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

from pathlib import Path

import pytest

from emulator.rendering.attribute_table import (
    BYTES_PER_ROW,
    TABLE_SIZE,
    get_attribute_palette_id,
)


def pack_attribute_byte(
    topleft: int,
    topright: int,
    bottomleft: int,
    bottomright: int,
) -> int:
    """
    Pack four 2-bit palette IDs into one attribute byte.

    This helper mirrors the documentation formula and makes the test examples
    easier to read.
    """
    return (
        (bottomright << 6)
        | (bottomleft << 4)
        | (topright << 2)
        | (topleft << 0)
    )


def make_attribute_table() -> bytearray:
    """Create a blank 64-byte attribute table."""
    return bytearray(TABLE_SIZE)


def test_attribute_table_file_exists():
    """
    Objective:
    Keep attribute-table bit decoding separate from nametable rendering.
    """
    assert Path("emulator/rendering/attribute_table.py").exists()


def test_attribute_table_declares_size_constants():
    """
    Objective:
    Name the visible nametable attribute-table geometry.
    """
    assert TABLE_SIZE == 64
    assert BYTES_PER_ROW == 8


def test_get_attribute_palette_id_function_exists():
    """
    Objective:
    Expose one helper for asking which background palette a tile coordinate uses.
    """
    assert callable(get_attribute_palette_id)


def test_all_zero_attribute_table_selects_palette_zero_everywhere():
    """
    Objective:
    If all attribute bytes are zero, every quadrant selects palette ID 0.
    """
    attribute_table = bytes(make_attribute_table())

    assert get_attribute_palette_id(attribute_table, tile_x=0, tile_y=0) == 0
    assert get_attribute_palette_id(attribute_table, tile_x=3, tile_y=3) == 0
    assert get_attribute_palette_id(attribute_table, tile_x=31, tile_y=29) == 0


def test_top_left_quadrant_reads_bits_zero_and_one():
    """
    Objective:
    Tiles in the top-left 2x2 quadrant read bits 0-1 of the attribute byte.

    Example byte:
        top-left = 1
        other quadrants = 0

        binary: 0b00_00_00_01
    """
    attribute_table = make_attribute_table()
    attribute_table[0] = pack_attribute_byte(
        topleft=1,
        topright=0,
        bottomleft=0,
        bottomright=0,
    )

    assert get_attribute_palette_id(bytes(attribute_table), 0, 0) == 1
    assert get_attribute_palette_id(bytes(attribute_table), 1, 0) == 1
    assert get_attribute_palette_id(bytes(attribute_table), 0, 1) == 1
    assert get_attribute_palette_id(bytes(attribute_table), 1, 1) == 1


def test_top_right_quadrant_reads_bits_two_and_three():
    """
    Objective:
    Tiles in the top-right 2x2 quadrant read bits 2-3 of the attribute byte.

    Example byte:
        top-right = 2
        binary contribution: 0b00_00_10_00
    """
    attribute_table = make_attribute_table()
    attribute_table[0] = pack_attribute_byte(
        topleft=0,
        topright=2,
        bottomleft=0,
        bottomright=0,
    )

    assert get_attribute_palette_id(bytes(attribute_table), 2, 0) == 2
    assert get_attribute_palette_id(bytes(attribute_table), 3, 0) == 2
    assert get_attribute_palette_id(bytes(attribute_table), 2, 1) == 2
    assert get_attribute_palette_id(bytes(attribute_table), 3, 1) == 2


def test_bottom_left_quadrant_reads_bits_four_and_five():
    """
    Objective:
    Tiles in the bottom-left 2x2 quadrant read bits 4-5 of the attribute byte.

    This protects against a common bug: accidentally treating bottom-left like
    top-left or bottom-right.
    """
    attribute_table = make_attribute_table()
    attribute_table[0] = pack_attribute_byte(
        topleft=0,
        topright=0,
        bottomleft=3,
        bottomright=0,
    )

    assert get_attribute_palette_id(bytes(attribute_table), 0, 2) == 3
    assert get_attribute_palette_id(bytes(attribute_table), 1, 2) == 3
    assert get_attribute_palette_id(bytes(attribute_table), 0, 3) == 3
    assert get_attribute_palette_id(bytes(attribute_table), 1, 3) == 3


def test_bottom_right_quadrant_reads_bits_six_and_seven():
    """
    Objective:
    Tiles in the bottom-right 2x2 quadrant read bits 6-7 of the attribute byte.
    """
    attribute_table = make_attribute_table()
    attribute_table[0] = pack_attribute_byte(
        topleft=0,
        topright=0,
        bottomleft=0,
        bottomright=2,
    )

    assert get_attribute_palette_id(bytes(attribute_table), 2, 2) == 2
    assert get_attribute_palette_id(bytes(attribute_table), 3, 2) == 2
    assert get_attribute_palette_id(bytes(attribute_table), 2, 3) == 2
    assert get_attribute_palette_id(bytes(attribute_table), 3, 3) == 2


def test_one_attribute_byte_can_store_four_different_palette_ids():
    """
    Objective:
    One attribute byte can select four different palette IDs for its four 2x2 tile
    quadrants.

    Packed example:
        top-left     = 0
        top-right    = 1
        bottom-left  = 2
        bottom-right = 3

    Byte layout:
        0b11_10_01_00
    """
    attribute_table = make_attribute_table()
    attribute_table[0] = pack_attribute_byte(
        topleft=0,
        topright=1,
        bottomleft=2,
        bottomright=3,
    )

    assert attribute_table[0] == 0b11_10_01_00
    assert get_attribute_palette_id(bytes(attribute_table), 0, 0) == 0
    assert get_attribute_palette_id(bytes(attribute_table), 2, 0) == 1
    assert get_attribute_palette_id(bytes(attribute_table), 0, 2) == 2
    assert get_attribute_palette_id(bytes(attribute_table), 2, 2) == 3


def test_neighboring_attribute_byte_starts_at_tile_x_four():
    """
    Objective:
    Since each attribute byte covers 4 tiles horizontally, tile_x=4 uses the next
    attribute byte in the same attribute-table row.
    """
    attribute_table = make_attribute_table()
    attribute_table[0] = pack_attribute_byte(0, 0, 0, 0)
    attribute_table[1] = pack_attribute_byte(2, 0, 0, 0)

    assert get_attribute_palette_id(bytes(attribute_table), 0, 0) == 0
    assert get_attribute_palette_id(bytes(attribute_table), 4, 0) == 2
    assert get_attribute_palette_id(bytes(attribute_table), 5, 1) == 2


def test_next_attribute_table_row_starts_at_tile_y_four():
    """
    Objective:
    Since each attribute byte covers 4 tiles vertically, tile_y=4 uses the next
    attribute-table row.
    """
    attribute_table = make_attribute_table()
    attribute_table[0] = pack_attribute_byte(0, 0, 0, 0)
    attribute_table[BYTES_PER_ROW] = pack_attribute_byte(3, 0, 0, 0)

    assert get_attribute_palette_id(bytes(attribute_table), 0, 0) == 0
    assert get_attribute_palette_id(bytes(attribute_table), 0, 4) == 3
    assert get_attribute_palette_id(bytes(attribute_table), 1, 5) == 3


def test_attribute_table_must_be_64_bytes():
    """
    Objective:
    Attribute table decoding expects the 64-byte attribute area, not the full
    1024-byte nametable page and not the 960-byte tile-ID area.
    """
    with pytest.raises(ValueError, match="Attribute table must be 64 bytes"):
        get_attribute_palette_id(bytes([0x00] * 63), tile_x=0, tile_y=0)

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

test_attribute_table_file_exists
test_attribute_table_declares_size_constants
test_get_attribute_palette_id_function_exists
test_all_zero_attribute_table_selects_palette_zero_everywhere
test_top_left_quadrant_reads_bits_zero_and_one
test_top_right_quadrant_reads_bits_two_and_three
test_bottom_left_quadrant_reads_bits_four_and_five
test_bottom_right_quadrant_reads_bits_six_and_seven
test_one_attribute_byte_can_store_four_different_palette_ids
test_neighboring_attribute_byte_starts_at_tile_x_four
test_next_attribute_table_row_starts_at_tile_y_four
test_attribute_table_must_be_64_bytes