275. 使用 NES 调色板的图案表

使用默认的 NES RGB 调色板渲染图案表帧缓冲。

第 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)

这在测试和调试调色板中很有用。现在我们有了默认的 NES RGB 调色板近似值，于是我们添加一个便捷的辅助函数:

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 字节，不要在本测试中使用商业 ROM 的 CHR 数据。

本步骤不涉及

pygame 显示
写入图像文件
名称表/背景渲染
PPU 调色板 RAM 查找
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