344. Уменьшить горизонтальный адрес vram

Отменить одно горизонтальное увеличение background-fetch на скопированном адресе.

Урок 344 из 356 · tests/chapter_13_scrolling/test_344_decrement_horizontal_vram_addr.py

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

emulator/ppu/ppu.py

Ссылки

https://www.nesdev.org/wiki/PPU_scrolling#Details

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

Точки 321-336 выполняют prefetch первых двух background плиток для следующего scanline. Каждый fetch плитки продвигает горизонтальный v, поэтому на точке 1 адрес уже на два столбца плиток впереди пикселей, хранящихся в background shifters:

intended visible coarse X = 5
prefetch tile 5 -> v advances to 6
prefetch tile 6 -> v advances to 7

dot 1:
    shifters begin displaying tile 5
    v already contains coarse X 7

Позже запись scanline скопирует v и отмотает эту копию дважды

7 -> 6 -> 5

Эта вспомогательная функция отменяет одно увеличение. Это не синхронизированная операция PPU, и она никогда не должна перемещать реальный PPU.vram_addr назад.

Нормальное поведение

coarse X 31 -> 30
coarse X 7  -> 6
coarse X 1  -> 0

Поведение на границе

coarse X 0 -> 31 and toggle horizontal nametable

Важные инварианты

только coarse X и, при переносе, горизонтальный nametable могут изменяться
каждое вертикальное и несвязанное поле остаётся неизменным
уменьшение является обратным протестированному горизонтальному увеличению
функция чистая и не изменяет PPU

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

NES PPU не выполняет это уменьшение во время рендеринга. Оно существует только для преобразования адреса fetch, который впереди дисплея, в адрес видимого viewport для существующего высокоуровневого рендерера.

Вне области действия

вызов вспомогательной функции из PPU.step()
запись 240 позиций scanline
изменения framebuffer или opacity-mask

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

# emulator/ppu/ppu.py

# --- NEW BLOCK: REVERSE ONE HORIZONTAL FETCH INCREMENT ---
def decrement_horizontal_vram_addr(vram_addr: int) -> int:
    coarse_x = vram_addr & 0b1_1111

    if coarse_x == 0:
        vram_addr = (
            (vram_addr & ~0b1_1111)
            | 0b1_1111
        )
        vram_addr ^= 0b000_01_00000_00000
        return vram_addr

    return vram_addr - 1

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

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

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

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

# emulator/ppu/ppu.py

# --- NEW BLOCK: REVERSE ONE HORIZONTAL FETCH INCREMENT ---
def decrement_horizontal_vram_addr(vram_addr: int) -> int:
    coarse_x = vram_addr & 0b1_1111

    if coarse_x == 0:
        vram_addr = (
            (vram_addr & ~0b1_1111)
            | 0b1_1111
        )
        vram_addr ^= 0b000_01_00000_00000
        return vram_addr

    return vram_addr - 1

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

import pytest

from emulator.ppu.ppu import (
    HORIZONTAL_SCROLL_BITS,
    PPU,
    decrement_horizontal_vram_addr,
    increment_horizontal_vram_addr,
)


COARSE_X_MASK = 0x001F
HORIZONTAL_NAMETABLE_BIT = 0x0400


@pytest.mark.parametrize("coarse_x", range(1, 32))
@pytest.mark.parametrize("nametable_x", [0, 1])
def test_nonzero_coarse_x_decrements_without_changing_nametable(
    coarse_x,
    nametable_x,
):
    """
    Objective:
    Reverse ordinary horizontal fetch increments without borrowing into other fields.
    """
    vertical_fields = 0x7BE0
    original = vertical_fields | (nametable_x << 10) | coarse_x

    result = decrement_horizontal_vram_addr(original)

    assert result & COARSE_X_MASK == coarse_x - 1
    assert result & HORIZONTAL_NAMETABLE_BIT == nametable_x << 10
    assert result & ~HORIZONTAL_SCROLL_BITS == original & ~HORIZONTAL_SCROLL_BITS


@pytest.mark.parametrize("nametable_x", [0, 1])
def test_coarse_x_zero_wraps_to_31_and_toggles_horizontal_nametable(
    nametable_x,
):
    """
    Objective:
    Reverse a fetch increment that crossed a logical horizontal nametable boundary.
    """
    vertical_fields = 0x7BE0
    original = vertical_fields | (nametable_x << 10)

    result = decrement_horizontal_vram_addr(original)

    assert result & COARSE_X_MASK == 31
    assert result & HORIZONTAL_NAMETABLE_BIT == (nametable_x ^ 1) << 10
    assert result & ~HORIZONTAL_SCROLL_BITS == original & ~HORIZONTAL_SCROLL_BITS


@pytest.mark.parametrize("coarse_x", range(32))
@pytest.mark.parametrize("nametable_x", [0, 1])
def test_decrement_reverses_horizontal_increment(coarse_x, nametable_x):
    """
    Objective:
    Prove the rewind operation is the inverse of one previously tested fetch increment.
    """
    original = 0x7BE0 | (nametable_x << 10) | coarse_x

    incremented = increment_horizontal_vram_addr(original)
    restored = decrement_horizontal_vram_addr(incremented)

    assert restored == original


@pytest.mark.parametrize("coarse_x", range(32))
@pytest.mark.parametrize("nametable_x", [0, 1])
def test_increment_reverses_horizontal_decrement(coarse_x, nametable_x):
    """
    Objective:
    Check the inverse relationship in the opposite operation order as well.
    """
    original = 0x7BE0 | (nametable_x << 10) | coarse_x

    decremented = decrement_horizontal_vram_addr(original)
    restored = increment_horizontal_vram_addr(decremented)

    assert restored == original


def test_rewind_preserves_unrelated_high_bit():
    """
    Objective:
    Preserve internal fields outside coarse X and horizontal nametable selection.
    """
    original = 0x8000 | 0x7BE0

    result = decrement_horizontal_vram_addr(original)

    assert result & 0x8000
    assert result & 0x7BE0 == original & 0x7BE0


def test_helper_is_pure_and_does_not_mutate_ppu_vram_addr():
    """
    Objective:
    Rewind only a copied value rather than the PPU's active rendering address.
    """
    ppu = PPU()
    ppu.vram_addr = HORIZONTAL_NAMETABLE_BIT | 7

    result = decrement_horizontal_vram_addr(ppu.vram_addr)

    assert result & COARSE_X_MASK == 6
    assert ppu.vram_addr == HORIZONTAL_NAMETABLE_BIT | 7

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

test_nonzero_coarse_x_decrements_without_changing_nametable
test_coarse_x_zero_wraps_to_31_and_toggles_horizontal_nametable
test_decrement_reverses_horizontal_increment
test_increment_reverses_horizontal_decrement
test_rewind_preserves_unrelated_high_bit
test_helper_is_pure_and_does_not_mutate_ppu_vram_addr