342. 复制垂直滚动位

把垂直滚动字段从临时地址 t 复制到当前地址 v。

第 342 / 356 · tests/chapter_13_scrolling/test_342_copy_vertical_scroll_bits.py

要更新的文件

emulator/ppu/ppu.py

参考资料

https://www.nesdev.org/wiki/PPU_scrolling#During_dots_280_to_304_of_the_pre-render_scanline_(end_of_vblank)

为什么需要这一步

CPU 写入会在临时地址 t 中准备垂直滚动字段，而渲染使用的是当前地址 v。在预渲染扫描线期间，PPU 会有选择地刷新垂直字段：

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

垂直掩码

0b111_10_11111_00000 = 0x7BE0

所需结果

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

最小示例

v: horizontal state A, vertical state B
t: horizontal state C, vertical state D

result: horizontal state A, vertical state D

常见误解

垂直重载并不是 v = t。复制 t 的全部内容，会覆盖已经由水平重载独立准备好的水平状态。

超出范围

修改 PPU.step()
点 256 的垂直递增
预渲染的点 280-304
扫描线状态记录
帧缓冲渲染

完整示例实现

# emulator/ppu/ppu.py

# --- NEW LINE: FINE Y, VERTICAL NAMETABLE, AND COARSE Y ---
VERTICAL_SCROLL_BITS = 0b111_10_11111_00000


# --- NEW BLOCK: PURE VERTICAL t-TO-v COPY ---
def copy_vertical_scroll_bits(
    vram_addr: int,
    temp_vram_addr: int,
) -> int:
    return (
        (vram_addr & ~VERTICAL_SCROLL_BITS)
        | (temp_vram_addr & VERTICAL_SCROLL_BITS)
    )

运行本课

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

示例实现

完整示例实现

# emulator/ppu/ppu.py

# --- NEW LINE: FINE Y, VERTICAL NAMETABLE, AND COARSE Y ---
VERTICAL_SCROLL_BITS = 0b111_10_11111_00000


# --- NEW BLOCK: PURE VERTICAL t-TO-v COPY ---
def copy_vertical_scroll_bits(
    vram_addr: int,
    temp_vram_addr: int,
) -> int:
    return (
        (vram_addr & ~VERTICAL_SCROLL_BITS)
        | (temp_vram_addr & VERTICAL_SCROLL_BITS)
    )

查看测试代码test_342_copy_vertical_scroll_bits.py

import pytest

from emulator.ppu.ppu import (
    HORIZONTAL_SCROLL_BITS,
    PPU,
    VERTICAL_SCROLL_BITS,
    copy_vertical_scroll_bits,
)


FINE_Y_MASK = 0x7000
VERTICAL_NAMETABLE_BIT = 0x0800
HORIZONTAL_NAMETABLE_BIT = 0x0400
COARSE_Y_MASK = 0x03E0
COARSE_X_MASK = 0x001F


def make_vertical_fields(
    *,
    fine_y: int,
    nametable_y: int,
    coarse_y: int,
) -> int:
    """Pack only the vertical scrolling fields used by this operation."""
    return (
        ((fine_y & 0b111) << 12)
        | ((nametable_y & 1) << 11)
        | ((coarse_y & 0b1_1111) << 5)
    )


def test_vertical_scroll_mask_selects_only_vertical_fields():
    """
    Objective:
    Select fine Y, vertical nametable, and coarse Y without selecting horizontal
    nametable bit 10 or coarse X.
    """
    assert VERTICAL_SCROLL_BITS == 0x7BE0
    assert VERTICAL_SCROLL_BITS & FINE_Y_MASK == FINE_Y_MASK
    assert VERTICAL_SCROLL_BITS & VERTICAL_NAMETABLE_BIT
    assert VERTICAL_SCROLL_BITS & COARSE_Y_MASK == COARSE_Y_MASK
    assert (VERTICAL_SCROLL_BITS & HORIZONTAL_NAMETABLE_BIT) == 0
    assert (VERTICAL_SCROLL_BITS & COARSE_X_MASK) == 0


@pytest.mark.parametrize(
    ("fine_y", "nametable_y", "coarse_y"),
    [
        (0, 0, 0),
        (3, 1, 12),
        (7, 0, 29),
        (6, 1, 31),
    ],
)
def test_copy_uses_all_vertical_fields_from_temp_address(
    fine_y,
    nametable_y,
    coarse_y,
):
    """
    Objective:
    Copy representative values across the complete packed vertical state.
    """
    vram_addr = HORIZONTAL_NAMETABLE_BIT | 17
    temp_vertical = make_vertical_fields(
        fine_y=fine_y,
        nametable_y=nametable_y,
        coarse_y=coarse_y,
    )

    result = copy_vertical_scroll_bits(vram_addr, temp_vertical)

    assert result & VERTICAL_SCROLL_BITS == temp_vertical


def test_copy_preserves_horizontal_fields_from_current_address():
    """
    Objective:
    Keep coarse X and horizontal nametable from v while replacing vertical fields.
    """
    horizontal_v = HORIZONTAL_NAMETABLE_BIT | 23
    vram_addr = horizontal_v | make_vertical_fields(
        fine_y=1,
        nametable_y=0,
        coarse_y=2,
    )
    temp_vram_addr = make_vertical_fields(
        fine_y=6,
        nametable_y=1,
        coarse_y=28,
    )

    result = copy_vertical_scroll_bits(vram_addr, temp_vram_addr)

    assert result & HORIZONTAL_SCROLL_BITS == horizontal_v
    assert result & VERTICAL_SCROLL_BITS == temp_vram_addr


def test_copy_ignores_horizontal_fields_present_in_temp_address():
    """
    Objective:
    Horizontal values in t must remain deferred to the horizontal reload operation.
    """
    horizontal_v = HORIZONTAL_NAMETABLE_BIT | 5
    temp_horizontal = 30
    temp_vertical = make_vertical_fields(
        fine_y=4,
        nametable_y=1,
        coarse_y=10,
    )

    result = copy_vertical_scroll_bits(
        horizontal_v,
        temp_vertical | temp_horizontal,
    )

    assert result & HORIZONTAL_SCROLL_BITS == horizontal_v
    assert result & VERTICAL_SCROLL_BITS == temp_vertical


def test_copy_preserves_unrelated_high_bit_from_current_address():
    """
    Objective:
    Preserve internal bits outside the named vertical scrolling fields.
    """
    vram_addr = 0x8000 | HORIZONTAL_NAMETABLE_BIT | 7
    temp_vram_addr = make_vertical_fields(
        fine_y=7,
        nametable_y=1,
        coarse_y=31,
    )

    result = copy_vertical_scroll_bits(vram_addr, temp_vram_addr)

    assert result & 0x8000


def test_helper_is_pure_and_does_not_mutate_ppu_addresses():
    """
    Objective:
    Keep vertical field arithmetic independent before timing integration.
    """
    ppu = PPU()
    ppu.vram_addr = HORIZONTAL_NAMETABLE_BIT | 7
    ppu.temp_vram_addr = make_vertical_fields(
        fine_y=5,
        nametable_y=1,
        coarse_y=20,
    )

    original_v = ppu.vram_addr
    original_t = ppu.temp_vram_addr
    result = copy_vertical_scroll_bits(
        ppu.vram_addr,
        ppu.temp_vram_addr,
    )

    assert result & VERTICAL_SCROLL_BITS == original_t
    assert ppu.vram_addr == original_v
    assert ppu.temp_vram_addr == original_t

测试函数 (6)

test_vertical_scroll_mask_selects_only_vertical_fields
test_copy_uses_all_vertical_fields_from_temp_address
test_copy_preserves_horizontal_fields_from_current_address
test_copy_ignores_horizontal_fields_present_in_temp_address
test_copy_preserves_unrelated_high_bit_from_current_address
test_helper_is_pure_and_does_not_mutate_ppu_addresses