328. PPUCTRL 临时名称表位

将 PPUCTRL 的基础名称表选择复制到 temp_vram_addr。

第 328 / 356 · tests/chapter_13_scrolling/test_328_ppuctrl_temp_nametable_bits.py

需要更新的文件

emulator/ppu/ppu.py

参考文档

https://www.nesdev.org/wiki/PPU_scrolling#$2000_(PPUCTRL)_write
https://www.nesdev.org/wiki/PPU_registers

该步骤存在的原因

PPU 卷动地址由若干个 CPU 可见的寄存器写入组装而成。本项目已经处理了 $2005 PPUSCROLL 的大部分部分:

coarse X -> temp_vram_addr bits 0-4
coarse Y -> temp_vram_addr bits 5-9
fine Y   -> temp_vram_addr bits 12-14
fine X   -> separate fine_x field

缺失的部分是逻辑基础名称表选择

PPUCTRL bits 0-1 -> temp_vram_addr bits 10-11

没有这个连接,temp_vram_addr 的行为就好像卷动总是从逻辑名称表 0($2000)开始一样,即使游戏软件选择的是 $2400、$2800 或 $2C00。这样一来,未来的视口渲染器就会跨越错误的逻辑边界。

内部卷动布局

temp_vram_addr (t): yyy NN YYYYY XXXXX

XXXXX -> coarse X tile position
YYYYY -> coarse Y tile position
NN    -> logical nametable selection
yyy   -> fine Y pixel position

fine_x (x) is stored separately

PPUCTRL 映射

bits 0-1 = 00 -> logical nametable $2000
bits 0-1 = 01 -> logical nametable $2400
bits 0-1 = 10 -> logical nametable $2800
bits 0-1 = 11 -> logical nametable $2C00

建议的实现

# emulator/ppu/ppu.py

case 0x2000:
    self.ctrl = value

    # --- NEW LINE: COPY BASE NAMETABLE INTO temp_vram_addr: ...GH.. ........ <- value: ......GH
    self.temp_vram_addr = (self.temp_vram_addr & 0b1111_0011_1111_1111) | ((value & CTRL_BASE_NAMETABLE_MASK) << 10)
    # --- END NEW LINE ---

为什么要先清除第 10-11 位?游戏可能会从任意一个逻辑名称表切换到任意另一个逻辑名称表。仅使用 OR 运算只能设置新位,而无法清除旧位。先清除再插入的操作可以替换之前的选择,同时保留粗略 X、粗略 Y 和精细 Y。

为什么不使用旧的 scroll 字段?$2005 会接收两次写入,而兼容性 scroll 字段只存储最近的一个字节。temp_vram_addr 加上 fine_x 才能保留完整的硬件风格状态。

重要区别

本步骤只是记录逻辑名称表的选择。之后卡带镜像会将该逻辑选择映射到物理名称表 RAM 上。这两个操作本身都不会移动可见视口;视口提取/渲染将在之后的步骤中实现。

不在本步骤范围内

推导视口像素 X/Y
渲染相邻名称表
在精确的硬件时钟点将 t 传输到 v
修改 PpuBus 的镜像
商业 ROM 测试夹具

运行本课

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

示例实现

建议的实现

# emulator/ppu/ppu.py

case 0x2000:
    self.ctrl = value

    # --- NEW LINE: COPY BASE NAMETABLE INTO temp_vram_addr: ...GH.. ........ <- value: ......GH
    self.temp_vram_addr = (self.temp_vram_addr & 0b1111_0011_1111_1111) | ((value & CTRL_BASE_NAMETABLE_MASK) << 10)
    # --- END NEW LINE ---

查看测试代码test_328_ppuctrl_temp_nametable_bits.py

from emulator.ppu.ppu import CTRL_BASE_NAMETABLE_MASK, PPU


TEMP_NAMETABLE_BITS_MASK = 0b0000_1100_0000_0000


def selected_nametable_from_temp_addr(ppu: PPU) -> int:
    """Return the logical nametable index encoded in temp_vram_addr."""
    return (ppu.temp_vram_addr >> 10) & 0b11


def selected_nametable_base_addr(ppu: PPU) -> int:
    """Convert the temporary nametable index into its logical PPU base address."""
    return 0x2000 + selected_nametable_from_temp_addr(ppu) * 0x400


def test_ppuctrl_base_nametable_mask_names_lowest_two_bits():
    """
    Objective:
    Keep the CPU-visible PPUCTRL field explicit instead of spreading a magic value.
    """
    assert CTRL_BASE_NAMETABLE_MASK == 0b0000_0011


def test_ppuctrl_selection_zero_encodes_logical_nametable_2000():
    """
    Objective:
    PPUCTRL bits 00 select logical nametable 0 at $2000.
    """
    ppu = PPU()

    ppu.write_register(0x2000, 0b0000_0000)

    assert selected_nametable_from_temp_addr(ppu) == 0
    assert selected_nametable_base_addr(ppu) == 0x2000


def test_ppuctrl_selection_one_encodes_logical_nametable_2400():
    """
    Objective:
    PPUCTRL bits 01 select logical nametable 1 at $2400.
    """
    ppu = PPU()

    ppu.write_register(0x2000, 0b0000_0001)

    assert selected_nametable_from_temp_addr(ppu) == 1
    assert selected_nametable_base_addr(ppu) == 0x2400


def test_ppuctrl_selection_two_encodes_logical_nametable_2800():
    """
    Objective:
    PPUCTRL bits 10 select logical nametable 2 at $2800.
    """
    ppu = PPU()

    ppu.write_register(0x2000, 0b0000_0010)

    assert selected_nametable_from_temp_addr(ppu) == 2
    assert selected_nametable_base_addr(ppu) == 0x2800


def test_ppuctrl_selection_three_encodes_logical_nametable_2c00():
    """
    Objective:
    PPUCTRL bits 11 select logical nametable 3 at $2C00.
    """
    ppu = PPU()

    ppu.write_register(0x2000, 0b0000_0011)

    assert selected_nametable_from_temp_addr(ppu) == 3
    assert selected_nametable_base_addr(ppu) == 0x2C00


def test_ppuctrl_write_replaces_previous_nametable_selection():
    """
    Objective:
    Clear old bits before inserting new bits so selection can change from 11 back to
    00 rather than remaining stuck at table 3.
    """
    ppu = PPU()
    ppu.write_register(0x2000, 0b0000_0011)
    assert selected_nametable_from_temp_addr(ppu) == 3

    ppu.write_register(0x2000, 0b0000_0000)

    assert selected_nametable_from_temp_addr(ppu) == 0


def test_ppuctrl_write_preserves_other_temp_vram_address_bits():
    """
    Objective:
    PPUCTRL owns only temporary-address bits 10-11. Coarse X/Y and fine Y must remain
    unchanged.
    """
    ppu = PPU()
    original = 0b0111_0011_1010_0101
    ppu.temp_vram_addr = original

    ppu.write_register(0x2000, 0b0000_0010)

    assert (
        ppu.temp_vram_addr & ~TEMP_NAMETABLE_BITS_MASK
    ) == (
        original & ~TEMP_NAMETABLE_BITS_MASK
    )
    assert selected_nametable_from_temp_addr(ppu) == 2


def test_unrelated_ppuctrl_bits_do_not_change_temp_nametable_selection():
    """
    Objective:
    NMI, pattern-table, sprite-size, and VRAM-increment flags share PPUCTRL but must
    not leak into temporary-address bits 10-11.
    """
    ppu = PPU()
    unrelated_ctrl_bits = 0b1111_1100

    ppu.write_register(0x2000, unrelated_ctrl_bits)

    assert selected_nametable_from_temp_addr(ppu) == 0


def test_ppuctrl_register_still_preserves_complete_written_byte():
    """
    Objective:
    Adding internal scroll-state behavior must preserve the existing self.ctrl
    register contract used by NMI and pattern-table logic.
    """
    ppu = PPU()
    value = 0b1011_1101

    ppu.write_register(0x2000, value)

    assert ppu.ctrl == value
    assert selected_nametable_from_temp_addr(ppu) == (value & 0b11)


def test_ppuctrl_value_is_masked_to_one_byte_before_scroll_state_update():
    """
    Objective:
    Preserve the register-write invariant that host integers are reduced to one byte
    before decoding PPUCTRL fields.
    """
    ppu = PPU()

    ppu.write_register(0x2000, 0x102)

    assert ppu.ctrl == 0x02
    assert selected_nametable_from_temp_addr(ppu) == 2

测试函数 (10)

test_ppuctrl_base_nametable_mask_names_lowest_two_bits
test_ppuctrl_selection_zero_encodes_logical_nametable_2000
test_ppuctrl_selection_one_encodes_logical_nametable_2400
test_ppuctrl_selection_two_encodes_logical_nametable_2800
test_ppuctrl_selection_three_encodes_logical_nametable_2c00
test_ppuctrl_write_replaces_previous_nametable_selection
test_ppuctrl_write_preserves_other_temp_vram_address_bits
test_unrelated_ppuctrl_bits_do_not_change_temp_nametable_selection
test_ppuctrl_register_still_preserves_complete_written_byte
test_ppuctrl_value_is_masked_to_one_byte_before_scroll_state_update