328. PPUCTRL: биты nametable во временном регистре

Скопировать выбор базового nametable из 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

Недостающая часть — это выбор логического базового nametable

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

Без этого соединения temp_vram_addr ведёт себя так, будто прокрутка всегда начинается с логического nametable 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? Игра может переключиться с любого логического nametable на любой другой. Использование только OR устанавливало бы новые биты, но не могло бы очистить старые. Операция «очистить, затем вставить» заменяет предыдущий выбор, сохраняя при этом грубый X, грубый Y и тонкий Y.

Почему не использовать старое поле scroll? $2005 получает две записи, но поле scroll, используемое для совместимости, хранит только самый последний байт. temp_vram_addr вместе с fine_x сохраняют полное состояние в аппаратном стиле.

Важное различие

Этот шаг фиксирует выбор логического nametable. Затем зеркалирование картриджа отображает этот логический выбор на физическую RAM nametable. Ни одна из этих операций сама по себе не перемещает видимую область просмотра; извлечение/рендеринг области просмотра появятся в более поздних шагах.

Вне рамок

вычисление пиксельных X/Y области просмотра
рендеринг соседних nametable
перенос 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