277. 使用 NES 调色板的名称表

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

第 277 / 356 · tests/chapter_05_rendering_pipeline/test_277_nametable_with_nes_palette.py

待更新的文件

emulator/rendering/nametable_renderer.py

为什么需要这一步

通用的名称表渲染器支持自定义调色板

nametable_to_framebuffer(nametable_bytes, pattern_table_bytes, palette)

这在测试和调试调色板中很有用。现在我们有了 NES_PALETTE_RGB，于是我们添加一个使用默认调色板的辅助函数:

nametable_to_nes_framebuffer(nametable_bytes, pattern_table_bytes)

这与上一个渲染步骤中的图案表辅助函数是对应的。

它应该做什么

nametable_to_nes_framebuffer(nametable_bytes, pattern_table_bytes)
    -> nametable_to_framebuffer(
           nametable_bytes,
           pattern_table_bytes,
           NES_PALETTE_RGB,
       )

建议的实现示例

from emulator.rendering.nes_palette import NES_PALETTE_RGB


def nametable_to_nes_framebuffer(
    nametable_bytes: bytes,
    pattern_table_bytes: bytes,
) -> Framebuffer:
    return nametable_to_framebuffer(
        nametable_bytes,
        pattern_table_bytes,
        NES_PALETTE_RGB,
    )

重要的简化

这里仍然对每个图块使用同一个共享调色板，尚未解码 64 字节的属性表，也还没有读取 $3F00-$3F1F 处的 PPU 调色板 RAM。这可以作为一个实用的调试/简单渲染器。之后的渲染器会使用属性表在不同的背景调色板之间进行选择。

重要的测试数据规则

只使用合成的名称表/CHR 字节，不要在本测试中使用商业 ROM 数据。

本步骤不涉及

属性表调色板选择
PPU 调色板 RAM 查找
滚动
精灵
OAMDMA
pygame 显示

运行本课

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

示例实现

建议的实现示例

from emulator.rendering.nes_palette import NES_PALETTE_RGB


def nametable_to_nes_framebuffer(
    nametable_bytes: bytes,
    pattern_table_bytes: bytes,
) -> Framebuffer:
    return nametable_to_framebuffer(
        nametable_bytes,
        pattern_table_bytes,
        NES_PALETTE_RGB,
    )

查看测试代码test_277_nametable_with_nes_palette.py

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE
from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.nametable_renderer import (
    NAMETABLE_SIZE,
    nametable_to_framebuffer,
    nametable_to_nes_framebuffer,
)
from emulator.rendering.nes_palette import NES_PALETTE_RGB


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


def make_empty_nametable() -> bytearray:
    """Create the visible 960-byte nametable tile-ID area."""
    return bytearray(NAMETABLE_SIZE)


def test_nametable_to_nes_framebuffer_function_exists():
    """
    Objective:
    Expose an explicit helper for rendering simplified nametable output using the
    default NES RGB palette approximation.
    """
    assert callable(nametable_to_nes_framebuffer)


def test_nametable_to_nes_framebuffer_returns_256_by_240_framebuffer():
    """
    Objective:
    The default-palette helper keeps the standard visible NES background size.
    """
    nametable = bytes(make_empty_nametable())
    pattern_table = bytes(make_empty_pattern_table())

    framebuffer = nametable_to_nes_framebuffer(nametable, pattern_table)

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


def test_empty_nametable_and_empty_pattern_table_use_nes_palette_color_zero():
    """
    Objective:
    Empty CHR bytes decode to color index 0. With the default helper, that index
    should map to NES_PALETTE_RGB[0].
    """
    nametable = bytes(make_empty_nametable())
    pattern_table = bytes(make_empty_pattern_table())

    framebuffer = nametable_to_nes_framebuffer(nametable, pattern_table)

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


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

    Setup:
        nametable[0] = 1, so tile #1 appears at the top-left background cell.

        tile #1 row 0:
            low bitplane  = 0xFF
            high bitplane = 0xFF

        Each pixel on row 0 decodes to binary 11, color index 3.
    """
    nametable = make_empty_nametable()
    nametable[0] = 1

    pattern_table = make_empty_pattern_table()
    tile_1_offset = 16
    pattern_table[tile_1_offset + 0] = 0xFF
    pattern_table[tile_1_offset + 8] = 0xFF

    framebuffer = nametable_to_nes_framebuffer(bytes(nametable), bytes(pattern_table))

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


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

    It should produce the same framebuffer as:
        nametable_to_framebuffer(nametable, pattern_table, NES_PALETTE_RGB)
    """
    nametable = make_empty_nametable()
    nametable[1] = 2

    pattern_table = make_empty_pattern_table()
    tile_2_offset = 2 * 16
    pattern_table[tile_2_offset + 0] = 0b0101_0101
    pattern_table[tile_2_offset + 8] = 0b0011_0011

    generic = nametable_to_framebuffer(
        bytes(nametable),
        bytes(pattern_table),
        NES_PALETTE_RGB,
    )
    default_nes = nametable_to_nes_framebuffer(bytes(nametable), bytes(pattern_table))

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

测试函数 (5)

test_nametable_to_nes_framebuffer_function_exists
test_nametable_to_nes_framebuffer_returns_256_by_240_framebuffer
test_empty_nametable_and_empty_pattern_table_use_nes_palette_color_zero
test_synthetic_top_left_tile_color_index_three_uses_nes_palette_color_three
test_nes_palette_helper_matches_generic_renderer_with_nes_palette