344. 递减水平 vram 地址

在一份复制的地址上逆转一次水平背景获取递增。

第 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 会为下一条扫描线预取前两个背景图块。每次图块获取都会推进水平 v，因此在点 1，该地址已经比背景移位寄存器中存储的像素超前了两个图块列：

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

稍后的扫描线记录会复制 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

重要不变量

只有粗X以及回绕时的水平命名表可能改变
所有垂直字段和无关字段都保持不变
递减是已测试的水平递增的逆操作
该函数是纯函数，不会修改 PPU

常见误解

NES PPU 不会在渲染期间执行这种递减。它存在的唯一目的，是为现有的高层渲染器把超前于显示的获取地址换算成可见的视口地址。

超出范围

从 PPU.step() 调用该辅助函数
记录 240 个扫描线位置
帧缓冲或不透明度掩码的变更

完整示例实现

# 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