281. 带调色板 RAM 的名称表

使用属性表和 PPU 调色板 RAM 字节渲染名称表背景。

第 281 / 356 · tests/chapter_05_rendering_pipeline/test_281_nametable_with_palette_ram.py

待更新文件

emulator/rendering/nametable_renderer.py

为什么需要这一步

前面的步骤已经分别构建了各个组成部分

attribute table
    -> palette ID for each tile coordinate

palette RAM bytes
    -> four RGB background palettes

nametable + attributes + background palettes
    -> framebuffer

这一步将这些部分组合成一个纯渲染辅助函数

nametable_with_palette_ram_to_framebuffer(
    nametable_bytes,
    attribute_table,
    pattern_table_bytes,
    palette_ram,
)

它应该做什么

background_palettes = build_background_palettes_from_palette_ram(palette_ram)

return nametable_with_attributes_to_framebuffer(
    nametable_bytes,
    attribute_table,
    pattern_table_bytes,
    background_palettes,
)

为什么这有用

这个辅助函数接受更接近真实 PPU 渲染输入形态的数据，同时保持完全可测试：

nametable visible tile bytes
attribute table bytes
pattern table CHR bytes
background palette RAM bytes

依然是纯数据

没有 PPU 总线读取，没有 pygame，没有窗口，没有帧循环。

重要的硬件模型

CHR pixel color index 0-3
    -> attribute table selects background palette ID 0-3
    -> palette RAM selects NES color index $00-$3F
    -> NES RGB palette converts to RGB
    -> framebuffer pixel

建议的实现示例

from emulator.rendering.palette_ram import build_background_palettes_from_palette_ram


def nametable_with_palette_ram_to_framebuffer(
    nametable_bytes: bytes,
    attribute_table: bytes,
    pattern_table_bytes: bytes,
    palette_ram: bytes,
) -> Framebuffer:
    background_palettes = build_background_palettes_from_palette_ram(palette_ram)

    return nametable_with_attributes_to_framebuffer(
        nametable_bytes,
        attribute_table,
        pattern_table_bytes,
        background_palettes,
    )

范围之外

从 PPU 总线读取名称表/调色板字节
调色板 RAM 镜像
滚动
精灵
OAMDMA
pygame 显示

运行本课

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

示例实现

它应该做什么

background_palettes = build_background_palettes_from_palette_ram(palette_ram)

return nametable_with_attributes_to_framebuffer(
    nametable_bytes,
    attribute_table,
    pattern_table_bytes,
    background_palettes,
)

建议的实现示例

from emulator.rendering.palette_ram import build_background_palettes_from_palette_ram


def nametable_with_palette_ram_to_framebuffer(
    nametable_bytes: bytes,
    attribute_table: bytes,
    pattern_table_bytes: bytes,
    palette_ram: bytes,
) -> Framebuffer:
    background_palettes = build_background_palettes_from_palette_ram(palette_ram)

    return nametable_with_attributes_to_framebuffer(
        nametable_bytes,
        attribute_table,
        pattern_table_bytes,
        background_palettes,
    )

查看测试代码test_281_nametable_with_palette_ram.py

from emulator.ppu.chr_decoder import PATTERN_TABLE_SIZE
from emulator.rendering.attribute_table import TABLE_SIZE
from emulator.rendering.nametable_renderer import (
    NAMETABLE_SIZE,
    nametable_with_attributes_to_framebuffer,
    nametable_with_palette_ram_to_framebuffer,
)
from emulator.rendering.nes_palette import get_nes_rgb_color
from emulator.rendering.palette_ram import build_background_palettes_from_palette_ram


def pack_attribute_byte(
    topleft: int,
    topright: int,
    bottomleft: int,
    bottomright: int,
) -> int:
    """Pack four 2-bit palette IDs into one NES attribute byte."""
    return (
        (bottomright << 6)
        | (bottomleft << 4)
        | (topright << 2)
        | (topleft << 0)
    )


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 make_empty_attribute_table() -> bytearray:
    """Create one synthetic 64-byte attribute table."""
    return bytearray(TABLE_SIZE)


def make_background_palette_ram() -> bytes:
    """
    Create synthetic $3F00-$3F0F background palette RAM bytes.

    Values are NES color indexes, not RGB colors.
    """
    return bytes([
        0x0F, 0x01, 0x02, 0x03,
        0x04, 0x11, 0x12, 0x13,
        0x08, 0x21, 0x22, 0x23,
        0x0C, 0x31, 0x32, 0x33,
    ])


def set_tile_row_to_color_index(
    pattern_table: bytearray,
    tile_id: int,
    row: int,
    color_index: int,
) -> None:
    """Set one synthetic tile row to a constant CHR color index."""
    tile_offset = tile_id * 16
    low_bit = color_index & 0b01
    high_bit = (color_index >> 1) & 0b01

    pattern_table[tile_offset + row] = 0xFF if low_bit else 0x00
    pattern_table[tile_offset + 8 + row] = 0xFF if high_bit else 0x00


def test_nametable_with_palette_ram_to_framebuffer_function_exists():
    """
    Objective:
    Expose one pure helper for rendering background bytes using palette RAM bytes.
    """
    assert callable(nametable_with_palette_ram_to_framebuffer)


def test_nametable_with_palette_ram_returns_256_by_240_framebuffer():
    """
    Objective:
    The composed helper keeps the normal NES visible background dimensions.
    """
    framebuffer = nametable_with_palette_ram_to_framebuffer(
        bytes(make_empty_nametable()),
        bytes(make_empty_attribute_table()),
        bytes(make_empty_pattern_table()),
        make_background_palette_ram(),
    )

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


def test_color_index_zero_uses_backdrop_color_from_palette_ram():
    """
    Objective:
    Empty CHR bytes decode to color index 0. Background color index 0 uses the
    shared backdrop color from palette RAM entry $3F00.
    """
    framebuffer = nametable_with_palette_ram_to_framebuffer(
        bytes(make_empty_nametable()),
        bytes(make_empty_attribute_table()),
        bytes(make_empty_pattern_table()),
        make_background_palette_ram(),
    )

    assert framebuffer.get_pixel(0, 0) == get_nes_rgb_color(0x0F)
    assert framebuffer.get_pixel(255, 239) == get_nes_rgb_color(0x0F)


def test_attribute_selected_palette_uses_palette_ram_entries_for_final_rgb():
    """
    Objective:
    Validate the full lookup chain:

        tile coordinate (2, 0)
            -> top-right attribute quadrant
            -> palette ID 1

        CHR pixel color index 3
            -> background palette 1 entry 3
            -> palette RAM value $13
            -> get_nes_rgb_color($13)
    """
    nametable = make_empty_nametable()
    nametable[2] = 1

    attribute_table = make_empty_attribute_table()
    attribute_table[0] = pack_attribute_byte(
        topleft=0,
        topright=1,
        bottomleft=2,
        bottomright=3,
    )

    pattern_table = make_empty_pattern_table()
    set_tile_row_to_color_index(pattern_table, tile_id=1, row=0, color_index=3)

    framebuffer = nametable_with_palette_ram_to_framebuffer(
        bytes(nametable),
        bytes(attribute_table),
        bytes(pattern_table),
        make_background_palette_ram(),
    )

    assert framebuffer.get_pixel(16, 0) == get_nes_rgb_color(0x13)


def test_each_attribute_quadrant_can_select_different_palette_ram_entries():
    """
    Objective:
    One attribute byte can select four different background palettes, and those
    palettes are resolved from palette RAM.
    """
    nametable = make_empty_nametable()
    nametable[0] = 1
    nametable[2] = 1
    nametable[2 * 32] = 1
    nametable[(2 * 32) + 2] = 1

    attribute_table = make_empty_attribute_table()
    attribute_table[0] = pack_attribute_byte(0, 1, 2, 3)

    pattern_table = make_empty_pattern_table()
    set_tile_row_to_color_index(pattern_table, tile_id=1, row=0, color_index=2)

    framebuffer = nametable_with_palette_ram_to_framebuffer(
        bytes(nametable),
        bytes(attribute_table),
        bytes(pattern_table),
        make_background_palette_ram(),
    )

    assert framebuffer.get_pixel(0, 0) == get_nes_rgb_color(0x02)
    assert framebuffer.get_pixel(16, 0) == get_nes_rgb_color(0x12)
    assert framebuffer.get_pixel(0, 16) == get_nes_rgb_color(0x22)
    assert framebuffer.get_pixel(16, 16) == get_nes_rgb_color(0x32)


def test_palette_ram_helper_matches_manual_composition():
    """
    Objective:
    nametable_with_palette_ram_to_framebuffer is a convenience composition helper,
    not a separate rendering algorithm.

    It should match:
        build_background_palettes_from_palette_ram(...)
        nametable_with_attributes_to_framebuffer(..., background_palettes)
    """
    nametable = make_empty_nametable()
    nametable[2] = 1

    attribute_table = make_empty_attribute_table()
    attribute_table[0] = pack_attribute_byte(0, 1, 2, 3)

    pattern_table = make_empty_pattern_table()
    set_tile_row_to_color_index(pattern_table, tile_id=1, row=0, color_index=3)

    palette_ram = make_background_palette_ram()
    background_palettes = build_background_palettes_from_palette_ram(palette_ram)

    manual = nametable_with_attributes_to_framebuffer(
        bytes(nametable),
        bytes(attribute_table),
        bytes(pattern_table),
        background_palettes,
    )
    composed = nametable_with_palette_ram_to_framebuffer(
        bytes(nametable),
        bytes(attribute_table),
        bytes(pattern_table),
        palette_ram,
    )

    assert composed.width == manual.width
    assert composed.height == manual.height
    assert composed.pixels == manual.pixels

测试函数 (6)

test_nametable_with_palette_ram_to_framebuffer_function_exists
test_nametable_with_palette_ram_returns_256_by_240_framebuffer
test_color_index_zero_uses_backdrop_color_from_palette_ram
test_attribute_selected_palette_uses_palette_ram_entries_for_final_rgb
test_each_attribute_quadrant_can_select_different_palette_ram_entries
test_palette_ram_helper_matches_manual_composition