341. 递增垂直 vram 地址

递增当前渲染地址 v 的垂直分量。

第 341 / 356 · tests/chapter_13_scrolling/test_341_increment_vertical_vram_addr.py

要更新的文件

emulator/ppu/ppu.py

参考资料

https://www.nesdev.org/wiki/PPU_scrolling#Y_increment
https://www.nesdev.org/wiki/PPU_scrolling#Wrapping_around

为什么需要这一步

在点 256，PPU 将渲染地址推进一个像素行。与水平递增不同，垂直移动首先在当前 8 像素图块内部推进细Y：

yyy NN YYYYY XXXXX
+++    +++++
 |       +---- coarse Y: bits 5-9
 +------------ fine Y: bits 12-14

vertical nametable: bit 11

细Y行为

0 -> 1 -> 2 -> ... -> 7

当细Y已经是 7 时，它会回绕到 0，同时粗Y递增。

细Y回绕后的粗Y行为

coarse Y 0-28 -> increment by one
coarse Y 29   -> 0 and toggle vertical nametable
coarse Y 30   -> 31 through the normal increment branch
coarse Y 31   -> 0 without toggling vertical nametable

第 0-29 行是命名表的 30 个可见图块行。值 30 和 31 不是正常的可见行，但它们可能存在，因为粗Y是一个五位字段，而 CPU 的地址操作可以载入这些值。

为什么正常的细Y递增要加 $1000？细Y从第 12 位开始，所以加上 1 << 12 就会让该打包字段递增 1。从概念上讲，这并不意味着在 PPU 内存中移动了 4096 字节。

重要不变量

水平粗X和命名表选择保持不变
无关的内部地址位保持不变
垂直命名表位仅在第 29 行回绕时翻转
该辅助函数是纯函数，不会修改 PPU

常见误解

垂直递增并不简单地与水平递增对称。水平移动推进一个图块列；垂直移动推进一个细像素行，并且只在某些时候推进粗图块行。

超出范围

在点 256 调用该辅助函数
垂直的 t 到 v 复制
预渲染时序
扫描线视口记录
帧缓冲渲染

完整示例实现

# emulator/ppu/ppu.py

# --- NEW BLOCK: PURE VERTICAL v INCREMENT ---
def increment_vertical_vram_addr(vram_addr: int) -> int:
    fine_y = (vram_addr >> 12) & 0b111

    if fine_y < 7:
        return vram_addr + (1 << 12)

    vram_addr &= ~0b111_00_00000_00000
    coarse_y = (vram_addr >> 5) & 0b1_1111

    if coarse_y == 29:
        coarse_y = 0
        vram_addr ^= 0b000_10_00000_00000
    elif coarse_y == 31:
        coarse_y = 0
    else:
        coarse_y += 1

    return (
        (vram_addr & ~0b000_00_11111_00000)
        | (coarse_y << 5)
    )

运行本课

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

示例实现

完整示例实现

# emulator/ppu/ppu.py

# --- NEW BLOCK: PURE VERTICAL v INCREMENT ---
def increment_vertical_vram_addr(vram_addr: int) -> int:
    fine_y = (vram_addr >> 12) & 0b111

    if fine_y < 7:
        return vram_addr + (1 << 12)

    vram_addr &= ~0b111_00_00000_00000
    coarse_y = (vram_addr >> 5) & 0b1_1111

    if coarse_y == 29:
        coarse_y = 0
        vram_addr ^= 0b000_10_00000_00000
    elif coarse_y == 31:
        coarse_y = 0
    else:
        coarse_y += 1

    return (
        (vram_addr & ~0b000_00_11111_00000)
        | (coarse_y << 5)
    )

查看测试代码test_341_increment_vertical_vram_addr.py

import pytest

from emulator.ppu.ppu import PPU, increment_vertical_vram_addr


FINE_Y_MASK = 0x7000
COARSE_Y_MASK = 0x03E0
VERTICAL_NAMETABLE_BIT = 0x0800
VERTICAL_FIELDS_MASK = FINE_Y_MASK | COARSE_Y_MASK | VERTICAL_NAMETABLE_BIT
HORIZONTAL_FIELDS_MASK = 0x041F


def make_vram_addr(
    *,
    coarse_y: int,
    fine_y: int,
    nametable_y: int = 0,
    horizontal_fields: int = 0,
    unrelated_fields: int = 0,
) -> int:
    """Pack the fields needed for focused vertical-address tests."""
    return (
        ((fine_y & 0b111) << 12)
        | ((nametable_y & 1) << 11)
        | ((coarse_y & 0b1_1111) << 5)
        | (horizontal_fields & HORIZONTAL_FIELDS_MASK)
        | unrelated_fields
    )


@pytest.mark.parametrize("fine_y", range(7))
def test_fine_y_zero_through_six_increments_without_changing_coarse_y(fine_y):
    """
    Objective:
    Advance one pixel row inside the current tile before touching coarse Y.
    """
    original = make_vram_addr(
        coarse_y=12,
        fine_y=fine_y,
        nametable_y=1,
        horizontal_fields=0x0415,
        unrelated_fields=0x8000,
    )

    result = increment_vertical_vram_addr(original)

    assert (result & FINE_Y_MASK) >> 12 == fine_y + 1
    assert result & ~FINE_Y_MASK == original & ~FINE_Y_MASK


@pytest.mark.parametrize(
    ("coarse_y", "expected_coarse_y"),
    [
        (0, 1),
        (1, 2),
        (28, 29),
        (30, 31),
    ],
)
def test_fine_y_seven_wraps_and_normally_increments_coarse_y(
    coarse_y,
    expected_coarse_y,
):
    """
    Objective:
    Use the normal coarse-Y increment for every value except hardware-special rows 29
    and 31. This includes the representable out-of-range value 30.
    """
    original = make_vram_addr(
        coarse_y=coarse_y,
        fine_y=7,
        nametable_y=0,
        horizontal_fields=0x0412,
    )

    result = increment_vertical_vram_addr(original)

    assert (result & FINE_Y_MASK) == 0
    assert (result & COARSE_Y_MASK) >> 5 == expected_coarse_y
    assert (result & VERTICAL_NAMETABLE_BIT) == 0
    assert result & HORIZONTAL_FIELDS_MASK == original & HORIZONTAL_FIELDS_MASK


@pytest.mark.parametrize("starting_nametable_y", [0, 1])
def test_row_29_wraps_to_zero_and_toggles_vertical_nametable(
    starting_nametable_y,
):
    """
    Objective:
    Cross the normal 240-pixel nametable boundary after visible row 29.
    """
    original = make_vram_addr(
        coarse_y=29,
        fine_y=7,
        nametable_y=starting_nametable_y,
        horizontal_fields=0x0407,
    )

    result = increment_vertical_vram_addr(original)

    assert (result & FINE_Y_MASK) == 0
    assert (result & COARSE_Y_MASK) == 0
    assert (result & VERTICAL_NAMETABLE_BIT) == (
        (starting_nametable_y ^ 1) << 11
    )
    assert result & HORIZONTAL_FIELDS_MASK == original & HORIZONTAL_FIELDS_MASK


@pytest.mark.parametrize("starting_nametable_y", [0, 1])
def test_row_31_wraps_to_zero_without_toggling_vertical_nametable(
    starting_nametable_y,
):
    """
    Objective:
    Preserve the documented row-31 hardware rule independently of normal visible
    row-29 wrapping.
    """
    original = make_vram_addr(
        coarse_y=31,
        fine_y=7,
        nametable_y=starting_nametable_y,
        horizontal_fields=0x001F,
    )

    result = increment_vertical_vram_addr(original)

    assert (result & FINE_Y_MASK) == 0
    assert (result & COARSE_Y_MASK) == 0
    assert (result & VERTICAL_NAMETABLE_BIT) == (
        starting_nametable_y << 11
    )
    assert result & HORIZONTAL_FIELDS_MASK == original & HORIZONTAL_FIELDS_MASK


def test_vertical_increment_preserves_unrelated_high_bit():
    """
    Objective:
    Keep internal address bits outside the named vertical fields unchanged.
    """
    original = make_vram_addr(
        coarse_y=5,
        fine_y=7,
        unrelated_fields=0x8000,
    )

    result = increment_vertical_vram_addr(original)

    assert result & 0x8000


def test_helper_is_pure_and_does_not_mutate_ppu_vram_addr():
    """
    Objective:
    Keep vertical arithmetic independently testable before timing integration.
    """
    ppu = PPU()
    ppu.vram_addr = make_vram_addr(coarse_y=8, fine_y=3)

    result = increment_vertical_vram_addr(ppu.vram_addr)

    assert (result & FINE_Y_MASK) >> 12 == 4
    assert ppu.vram_addr == make_vram_addr(coarse_y=8, fine_y=3)

测试函数 (6)

test_fine_y_zero_through_six_increments_without_changing_coarse_y
test_fine_y_seven_wraps_and_normally_increments_coarse_y
test_row_29_wraps_to_zero_and_toggles_vertical_nametable
test_row_31_wraps_to_zero_without_toggling_vertical_nametable
test_vertical_increment_preserves_unrelated_high_bit
test_helper_is_pure_and_does_not_mutate_ppu_vram_addr