332. 将 PPU 逻辑名称表渲染为帧缓冲区

将一个所选的逻辑 PPU 名称表渲染为帧缓冲区。

第 332 / 356 · tests/chapter_13_scrolling/test_332_ppu_logical_nametable_to_framebuffer.py

待更新文件

emulator/rendering/ppu_background_renderer.py

参考

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

此步骤存在的原因

原始辅助函数总是渲染逻辑名称表 $2000。水平滚动还需要相邻的逻辑名称表，因此该辅助函数现在接受以下之一：

$2000, $2400, $2800, $2C00

相对于所选基址的内存布局

base + $000-$3BF: 960 visible tile IDs
base + $3C0-$3FF: 64 attribute bytes

兼容性

省略 base_nametable_addr 时仍必须渲染 $2000。因此现有调用方无需修改。

镜像边界

渲染通过 PpuBus 请求逻辑地址。PpuBus 仍然负责将这些地址映射到水平或垂直镜像的物理 VRAM。

范围之外

选择并组合两个相邻的帧缓冲区
不透明度掩码地址选择
与 Console 集成
垂直视口组合
pygame

示例实现

# emulator/rendering/ppu_background_renderer.py

# --- NEW LINES: ACCEPTED LOGICAL NAMETABLE BASE ADDRESSES ---
LOGICAL_NAMETABLE_BASE_ADDRS = (
    0x2000,
    0x2400,
    0x2800,
    0x2C00,
)


def ppu_background_to_framebuffer(
    ppu: PPU,
    # --- NEW LINE: OPTIONAL LOGICAL NAMETABLE SELECTION ---
    base_nametable_addr: int = BASE_NAMETABLE_ADDR,
) -> Framebuffer:
    # --- NEW BLOCK: REJECT NON-NAMETABLE BASE ADDRESSES ---
    if base_nametable_addr not in LOGICAL_NAMETABLE_BASE_ADDRS:
        raise ValueError(
            "Logical nametable base address must be $2000, $2400, $2800, $2C00"
        )

    nametable_bytes = bytes(
        # --- UPDATED LINE: READ FROM THE SELECTED NAMETABLE ---
        ppu.ppu_bus.read(base_nametable_addr + offset)
        for offset in range(NAMETABLE_SIZE)
    )

    # --- NEW LINE: DERIVE THE SELECTED ATTRIBUTE-TABLE BASE ---
    attribute_table_base = base_nametable_addr + NAMETABLE_SIZE
    attribute_table = bytes(
        # --- UPDATED LINE: READ THE SELECTED ATTRIBUTE TABLE ---
        ppu.ppu_bus.read(attribute_table_base + offset)
        for offset in range(ATTR_TABLE_SIZE)
    )

   ... 
   # Everything remains the same below this point

运行本课

uv run pytest tests/chapter_13_scrolling/test_332_ppu_logical_nametable_to_framebuffer.py -v

示例实现

# emulator/rendering/ppu_background_renderer.py

# --- NEW LINES: ACCEPTED LOGICAL NAMETABLE BASE ADDRESSES ---
LOGICAL_NAMETABLE_BASE_ADDRS = (
    0x2000,
    0x2400,
    0x2800,
    0x2C00,
)


def ppu_background_to_framebuffer(
    ppu: PPU,
    # --- NEW LINE: OPTIONAL LOGICAL NAMETABLE SELECTION ---
    base_nametable_addr: int = BASE_NAMETABLE_ADDR,
) -> Framebuffer:
    # --- NEW BLOCK: REJECT NON-NAMETABLE BASE ADDRESSES ---
    if base_nametable_addr not in LOGICAL_NAMETABLE_BASE_ADDRS:
        raise ValueError(
            "Logical nametable base address must be $2000, $2400, $2800, $2C00"
        )

    nametable_bytes = bytes(
        # --- UPDATED LINE: READ FROM THE SELECTED NAMETABLE ---
        ppu.ppu_bus.read(base_nametable_addr + offset)
        for offset in range(NAMETABLE_SIZE)
    )

    # --- NEW LINE: DERIVE THE SELECTED ATTRIBUTE-TABLE BASE ---
    attribute_table_base = base_nametable_addr + NAMETABLE_SIZE
    attribute_table = bytes(
        # --- UPDATED LINE: READ THE SELECTED ATTRIBUTE TABLE ---
        ppu.ppu_bus.read(attribute_table_base + offset)
        for offset in range(ATTR_TABLE_SIZE)
    )

   ... 
   # Everything remains the same below this point

查看测试代码test_332_ppu_logical_nametable_to_framebuffer.py

import pytest

from emulator.ppu.ppu import CTRL_BACKGROUND_PATTERN_TABLE, PPU
from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.nametable_renderer import NAMETABLE_SIZE
import emulator.rendering.ppu_background_renderer as background_renderer
from emulator.rendering.ppu_background_renderer import (
    ATTR_TABLE_SIZE,
    BASE_ATTR_TABLE_ADDR,
    BASE_NAMETABLE_ADDR,
    LOGICAL_NAMETABLE_BASE_ADDRS,
    PALETTE_RAM_ADDR,
    PATTERN_TABLE_1_ADDR,
    ppu_background_to_framebuffer,
)


class RecordingPpuBus:
    """Minimal bus double that records every logical address requested."""

    def __init__(self) -> None:
        self.read_addresses: list[int] = []

    def read(self, addr: int) -> int:
        self.read_addresses.append(addr)
        return addr & 0xFF


def replace_low_level_renderer(monkeypatch):
    """Capture extracted bytes without spending time decoding a full framebuffer."""
    captured: dict[str, bytes] = {}
    expected_framebuffer = Framebuffer()

    def fake_renderer(
        nametable_bytes: bytes,
        attribute_table: bytes,
        pattern_table_bytes: bytes,
        palette_ram: bytes,
    ) -> Framebuffer:
        captured["nametable"] = nametable_bytes
        captured["attributes"] = attribute_table
        captured["pattern_table"] = pattern_table_bytes
        captured["palette_ram"] = palette_ram
        return expected_framebuffer

    monkeypatch.setattr(
        background_renderer,
        "nametable_with_palette_ram_to_framebuffer",
        fake_renderer,
    )
    return captured, expected_framebuffer


@pytest.mark.parametrize("base", LOGICAL_NAMETABLE_BASE_ADDRS)
def test_selected_logical_base_reads_its_tile_and_attribute_ranges(monkeypatch, base):
    """
    Objective:
    Read tile IDs and attributes relative to each selected logical nametable base.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    replace_low_level_renderer(monkeypatch)

    ppu_background_to_framebuffer(ppu, base_nametable_addr=base)

    tile_reads = bus.read_addresses[:NAMETABLE_SIZE]
    attribute_start = NAMETABLE_SIZE
    attribute_end = attribute_start + ATTR_TABLE_SIZE
    attribute_reads = bus.read_addresses[attribute_start:attribute_end]

    assert tile_reads == list(range(base, base + NAMETABLE_SIZE))
    assert attribute_reads == list(
        range(base + NAMETABLE_SIZE, base + NAMETABLE_SIZE + ATTR_TABLE_SIZE)
    )


def test_omitted_base_preserves_historical_2000_behavior(monkeypatch):
    """
    Objective:
    Keep every existing one-argument caller compatible with the original helper.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    replace_low_level_renderer(monkeypatch)

    ppu_background_to_framebuffer(ppu)

    assert BASE_NAMETABLE_ADDR == 0x2000
    assert BASE_ATTR_TABLE_ADDR == 0x23C0
    assert bus.read_addresses[0] == BASE_NAMETABLE_ADDR
    assert bus.read_addresses[NAMETABLE_SIZE] == BASE_ATTR_TABLE_ADDR


def test_selected_nametable_still_uses_shared_pattern_and_palette_data(monkeypatch):
    """
    Objective:
    Generalizing nametable selection must not change PPUCTRL pattern-table selection
    or the shared palette-RAM address.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    ppu.ctrl = CTRL_BACKGROUND_PATTERN_TABLE
    captured, expected_framebuffer = replace_low_level_renderer(monkeypatch)

    result = ppu_background_to_framebuffer(
        ppu,
        base_nametable_addr=0x2400,
    )

    pattern_read_start = NAMETABLE_SIZE + ATTR_TABLE_SIZE
    palette_read_start = pattern_read_start + len(captured["pattern_table"])

    assert bus.read_addresses[pattern_read_start] == PATTERN_TABLE_1_ADDR
    assert bus.read_addresses[palette_read_start] == PALETTE_RAM_ADDR
    assert result is expected_framebuffer


@pytest.mark.parametrize("invalid_base", [0x0000, 0x23C0, 0x3000, 0x3F00])
def test_rejects_addresses_that_are_not_logical_nametable_bases(invalid_base):
    """
    Objective:
    Reject arbitrary addresses before performing partial or misleading bus reads.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)

    with pytest.raises(ValueError, match="Logical nametable base address"):
        ppu_background_to_framebuffer(
            ppu,
            base_nametable_addr=invalid_base,
        )

    assert bus.read_addresses == []


def test_renderer_requests_logical_addresses_and_leaves_mirroring_to_ppu_bus(monkeypatch):
    """
    Objective:
    The renderer must issue the selected logical address range without duplicating
    PpuBus nametable-normalization rules.
    """
    bus = RecordingPpuBus()
    ppu = PPU(ppu_bus=bus)
    replace_low_level_renderer(monkeypatch)

    ppu_background_to_framebuffer(ppu, base_nametable_addr=0x2C00)

    assert bus.read_addresses[0] == 0x2C00
    assert bus.read_addresses[NAMETABLE_SIZE - 1] == 0x2FBF
    assert bus.read_addresses[NAMETABLE_SIZE] == 0x2FC0
    assert bus.read_addresses[NAMETABLE_SIZE + ATTR_TABLE_SIZE - 1] == 0x2FFF

测试函数 (5)

test_selected_logical_base_reads_its_tile_and_attribute_ranges
test_omitted_base_preserves_historical_2000_behavior
test_selected_nametable_still_uses_shared_pattern_and_palette_data
test_rejects_addresses_that_are_not_logical_nametable_bases
test_renderer_requests_logical_addresses_and_leaves_mirroring_to_ppu_bus