339. Копирование битов горизонтальной прокрутки

Копировать поля горизонтальной прокрутки из временного адреса t в текущий адрес v.

Урок 339 из 356 · tests/chapter_13_scrolling/test_339_copy_horizontal_scroll_bits.py

Файл для обновления

emulator/ppu/ppu.py

Справочные материалы

https://www.nesdev.org/wiki/PPU_scrolling#During_rendering
https://www.nesdev.org/wiki/PPU_scrolling#At_dot_257_of_each_scanline

Зачем нужен этот шаг

Записи CPU подготавливают поля прокрутки во временном адресе t, но отрисовка фона использует текущий адрес v. PPU переносит только горизонтальные поля в точке горизонтальной перезагрузки:

yyy NN YYYYY XXXXX
    ||       +++++-- coarse X: bits 0-4
    |+-------------- horizontal nametable: bit 10
    +--------------- vertical nametable: bit 11, not copied here

Горизонтальная маска

0b000_01_00000_11111 = 0x041F

Требуемый результат

coarse X                    <- t
horizontal nametable       <- t
coarse Y                    <- original v
fine Y                      <- original v
vertical nametable         <- original v
every other unrelated bit  <- original v

Минимальный пример

v: coarse X 3,  horizontal nametable 0, vertical state A
t: coarse X 20, horizontal nametable 1, vertical state B

result: coarse X 20, horizontal nametable 1, vertical state A

Распространённое заблуждение

Горизонтальная перезагрузка — это не v = t. Копирование всего t заменило бы вертикальное состояние в неправильный момент. Более поздний шаг применит эту уже протестированную операцию в точке 257.

Вне объёма работ

изменение PPU.step()
таймирование в точке 257
горизонтальные инкременты адреса
вертикальные копирования из t в v
отрисовка фреймбуфера

Полный пример реализации

# emulator/ppu/ppu.py

# --- NEW LINE: COARSE X AND HORIZONTAL NAMETABLE FIELDS ---
HORIZONTAL_SCROLL_BITS = 0b000_01_00000_11111


# --- NEW BLOCK: PURE HORIZONTAL t-TO-v COPY ---
def copy_horizontal_scroll_bits(
    vram_addr: int,
    temp_vram_addr: int,
) -> int:
    return (
        (vram_addr & ~HORIZONTAL_SCROLL_BITS)
        | (temp_vram_addr & HORIZONTAL_SCROLL_BITS)
    )

Запустить этот урок

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

Пример реализации

Полный пример реализации

# emulator/ppu/ppu.py

# --- NEW LINE: COARSE X AND HORIZONTAL NAMETABLE FIELDS ---
HORIZONTAL_SCROLL_BITS = 0b000_01_00000_11111


# --- NEW BLOCK: PURE HORIZONTAL t-TO-v COPY ---
def copy_horizontal_scroll_bits(
    vram_addr: int,
    temp_vram_addr: int,
) -> int:
    return (
        (vram_addr & ~HORIZONTAL_SCROLL_BITS)
        | (temp_vram_addr & HORIZONTAL_SCROLL_BITS)
    )

Показать код тестаtest_339_copy_horizontal_scroll_bits.py

import pytest

from emulator.ppu.ppu import (
    HORIZONTAL_SCROLL_BITS,
    PPU,
    copy_horizontal_scroll_bits,
)


COARSE_X_MASK = 0x001F
HORIZONTAL_NAMETABLE_BIT = 0x0400
VERTICAL_FIELDS_MASK = 0x7BE0


def test_horizontal_scroll_mask_selects_coarse_x_and_bit_10_only():
    """
    Objective:
    Prevent accidentally selecting vertical nametable bit 11 instead of horizontal
    nametable bit 10.
    """
    assert HORIZONTAL_SCROLL_BITS == 0x041F
    assert HORIZONTAL_SCROLL_BITS & COARSE_X_MASK == COARSE_X_MASK
    assert HORIZONTAL_SCROLL_BITS & HORIZONTAL_NAMETABLE_BIT
    assert (HORIZONTAL_SCROLL_BITS & 0x0800) == 0


@pytest.mark.parametrize("coarse_x", [0, 1, 15, 30, 31])
@pytest.mark.parametrize("nametable_x", [0, 1])
def test_copy_uses_horizontal_fields_from_temp_address(coarse_x, nametable_x):
    """
    Objective:
    Copy representative coarse-X values and both logical horizontal nametables from t.
    """
    vram_addr = HORIZONTAL_NAMETABLE_BIT | 7
    temp_vram_addr = coarse_x | (nametable_x << 10)

    result = copy_horizontal_scroll_bits(vram_addr, temp_vram_addr)

    assert result & COARSE_X_MASK == coarse_x
    assert (result & HORIZONTAL_NAMETABLE_BIT) == (nametable_x << 10)


def test_copy_preserves_vertical_fields_from_current_address():
    """
    Objective:
    The horizontal reload must not import coarse Y, fine Y, or vertical nametable from
    temporary address t.
    """
    vertical_v = 0x7BE0
    horizontal_t = HORIZONTAL_NAMETABLE_BIT | 20
    vram_addr = vertical_v | 3
    temp_vram_addr = horizontal_t

    result = copy_horizontal_scroll_bits(vram_addr, temp_vram_addr)

    assert result & VERTICAL_FIELDS_MASK == vertical_v
    assert result & HORIZONTAL_SCROLL_BITS == horizontal_t


def test_copy_ignores_vertical_fields_present_in_temp_address():
    """
    Objective:
    Vertical bits in t remain deferred to the later vertical reload operation.
    """
    vram_addr = 0x0020
    temp_vram_addr = VERTICAL_FIELDS_MASK | HORIZONTAL_NAMETABLE_BIT | 12

    result = copy_horizontal_scroll_bits(vram_addr, temp_vram_addr)

    assert result & VERTICAL_FIELDS_MASK == vram_addr & VERTICAL_FIELDS_MASK
    assert result & HORIZONTAL_SCROLL_BITS == HORIZONTAL_NAMETABLE_BIT | 12


def test_copy_preserves_unrelated_high_bits_from_current_address():
    """
    Objective:
    Preserve internal address bits outside both named horizontal fields.
    """
    vram_addr = 0x8000 | VERTICAL_FIELDS_MASK
    temp_vram_addr = HORIZONTAL_NAMETABLE_BIT | 31

    result = copy_horizontal_scroll_bits(vram_addr, temp_vram_addr)

    assert result & 0x8000


def test_helper_is_pure_and_does_not_mutate_ppu_addresses():
    """
    Objective:
    Keep field-copy arithmetic independent before introducing timing behavior.
    """
    ppu = PPU()
    ppu.vram_addr = 3
    ppu.temp_vram_addr = HORIZONTAL_NAMETABLE_BIT | 20

    result = copy_horizontal_scroll_bits(
        ppu.vram_addr,
        ppu.temp_vram_addr,
    )

    assert result & HORIZONTAL_SCROLL_BITS == HORIZONTAL_NAMETABLE_BIT | 20
    assert ppu.vram_addr == 3
    assert ppu.temp_vram_addr == HORIZONTAL_NAMETABLE_BIT | 20

Тестовые функции (6)

test_horizontal_scroll_mask_selects_coarse_x_and_bit_10_only
test_copy_uses_horizontal_fields_from_temp_address
test_copy_preserves_vertical_fields_from_current_address
test_copy_ignores_vertical_fields_present_in_temp_address
test_copy_preserves_unrelated_high_bits_from_current_address
test_helper_is_pure_and_does_not_mutate_ppu_addresses