275. Таблица шаблонов с палитрой NES

Рендеринг фреймбуфера таблицы шаблонов с использованием палитры NES по умолчанию.

Урок 275 из 356 · tests/chapter_05_rendering_pipeline/test_275_pattern_table_with_nes_palette.py

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

emulator/rendering/pattern_table_renderer.py

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

Универсальный рендерер таблицы шаблонов уже поддерживает пользовательские палитры

pattern_table_to_framebuffer(pattern_table_bytes, palette)

Это полезно для тестов и отладочных палитр. Теперь, когда у нас есть RGB-аппроксимация палитры NES по умолчанию, добавим удобную вспомогательную функцию:

pattern_table_to_nes_framebuffer(pattern_table_bytes)

Эта вспомогательная функция делает путь с палитрой по умолчанию явным, не убирая поддержку пользовательских палитр.

Что она должна делать

pattern_table_to_nes_framebuffer(pattern_table_bytes)
    -> pattern_table_to_framebuffer(pattern_table_bytes, NES_PALETTE_RGB)

Пример возможной реализации

from emulator.rendering.nes_palette import NES_PALETTE_RGB


def pattern_table_to_nes_framebuffer(
    pattern_table_bytes: bytes,
) -> Framebuffer:
    return pattern_table_to_framebuffer(pattern_table_bytes, NES_PALETTE_RGB)

Почему бы не сделать NES_PALETTE_RGB аргументом по умолчанию?

Это тоже сработало бы

def pattern_table_to_framebuffer(pattern_table_bytes, palette=NES_PALETTE_RGB):
    ...

Но отдельная вспомогательная функция понятнее для курса

pattern_table_to_framebuffer(..., palette)
    custom palette path

pattern_table_to_nes_framebuffer(...)
    default NES palette path

Примечание: этот тест использует только синтетические байты CHR. Не используйте в этом тесте данные CHR из коммерческих ROM.

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

отображение через pygame
запись файлов изображений
рендеринг таблицы имён/фона
поиск в палитровой RAM PPU
акцентированные цвета PPUMASK
спрайты

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

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

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

Пример возможной реализации

from emulator.rendering.nes_palette import NES_PALETTE_RGB


def pattern_table_to_nes_framebuffer(
    pattern_table_bytes: bytes,
) -> Framebuffer:
    return pattern_table_to_framebuffer(pattern_table_bytes, NES_PALETTE_RGB)

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

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE
from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.nes_palette import NES_PALETTE_RGB
from emulator.rendering.pattern_table_renderer import (
    pattern_table_to_framebuffer,
    pattern_table_to_nes_framebuffer,
)


def make_empty_pattern_table() -> bytearray:
    """Create one synthetic 4096-byte pattern table."""
    return bytearray(PATTERN_TABLE_SIZE)


def test_pattern_table_to_nes_framebuffer_function_exists():
    """
    Objective:
    Expose an explicit helper for rendering pattern-table debug output using the
    default NES RGB palette approximation.
    """
    assert callable(pattern_table_to_nes_framebuffer)


def test_pattern_table_to_nes_framebuffer_returns_128_by_128_framebuffer():
    """
    Objective:
    The default-palette helper keeps the same pattern-table debug dimensions.
    """
    pattern_table = bytes(make_empty_pattern_table())

    framebuffer = pattern_table_to_nes_framebuffer(pattern_table)

    assert isinstance(framebuffer, Framebuffer)
    assert framebuffer.width == 128
    assert framebuffer.height == 128
    assert len(framebuffer.pixels) == 128 * 128


def test_empty_pattern_table_uses_nes_palette_color_zero():
    """
    Objective:
    Empty CHR bytes decode to color index 0, so every framebuffer pixel should use
    NES_PALETTE_RGB[0].
    """
    pattern_table = bytes(make_empty_pattern_table())

    framebuffer = pattern_table_to_nes_framebuffer(pattern_table)

    assert framebuffer.get_pixel(0, 0) == NES_PALETTE_RGB[0]
    assert framebuffer.get_pixel(127, 127) == NES_PALETTE_RGB[0]


def test_synthetic_tile_color_index_three_uses_nes_palette_color_three():
    """
    Objective:
    A synthetic CHR tile that decodes to color index 3 should become
    NES_PALETTE_RGB[3] in the framebuffer.

    CHR tile encoding:
        low bitplane byte  = 0xFF
        high bitplane byte = 0xFF

    For each pixel:
        low bit  = 1
        high bit = 1
        color index = binary 11 = 3
    """
    pattern_table = make_empty_pattern_table()

    # First tile, row 0 only: all pixels become color index 3.
    pattern_table[0] = 0xFF
    pattern_table[8] = 0xFF

    framebuffer = pattern_table_to_nes_framebuffer(bytes(pattern_table))

    assert framebuffer.get_pixel(0, 0) == NES_PALETTE_RGB[3]
    assert framebuffer.get_pixel(7, 0) == NES_PALETTE_RGB[3]

    # Row 1 was left as zero bytes, so it still maps to color index 0.
    assert framebuffer.get_pixel(0, 1) == NES_PALETTE_RGB[0]


def test_nes_palette_helper_matches_generic_renderer_with_nes_palette():
    """
    Objective:
    pattern_table_to_nes_framebuffer is a convenience wrapper, not a separate
    rendering algorithm.

    It should produce the same pixels as:
        pattern_table_to_framebuffer(pattern_table, NES_PALETTE_RGB)
    """
    pattern_table = make_empty_pattern_table()

    # First tile, row 0: repeating 0, 1, 2, 3 pattern.
    pattern_table[0] = 0b0101_0101
    pattern_table[8] = 0b0011_0011

    generic = pattern_table_to_framebuffer(bytes(pattern_table), NES_PALETTE_RGB)
    default_nes = pattern_table_to_nes_framebuffer(bytes(pattern_table))

    assert default_nes.width == generic.width
    assert default_nes.height == generic.height
    assert default_nes.pixels == generic.pixels

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

test_pattern_table_to_nes_framebuffer_function_exists
test_pattern_table_to_nes_framebuffer_returns_128_by_128_framebuffer
test_empty_pattern_table_uses_nes_palette_color_zero
test_synthetic_tile_color_index_three_uses_nes_palette_color_three
test_nes_palette_helper_matches_generic_renderer_with_nes_palette