345. 记录可见扫描线滚动状态

在每条可见扫描线的点 1 记录有效视口状态。

第 345 / 356 · tests/chapter_13_scrolling/test_345_record_visible_scanline_scroll_state.py

要更新的文件

emulator/ppu/ppu.py

参考资料

https://www.nesdev.org/wiki/PPU_rendering#Cycles_1-256
https://www.nesdev.org/wiki/PPU_scrolling#Details

为什么需要这一步

现在 PPU 会按照水平和垂直渲染时序更新 v，但现有的高层渲染器是在整帧结束之后运行的。它需要一份简短的记录，记下代表每个可见屏幕行的有效地址。

一个不可变状态存储

vram_addr:
    the copied address represented by the prefetched pixels

fine_x:
    the separate 0-7 pixel offset inside the first tile

在点 1，真实的 v 超前两个图块列，因为点 321-336 已为当前扫描线预取了前两个图块。因此记录操作会执行：

copied visible v = real v rewound once, then rewound again

示例

current scanline = 20
real v coarse X  = 7

copied visible coarse X:
    7 -> 6 -> 5

stored destination:
    current_scanline_scroll_states[20]

回退改变的是水平图块位置，而不是扫描线索引。该状态属于当前扫描线 20，而不是扫描线 18。

记录条件

背景或精灵渲染已启用
扫描线可见：0-239
当前点为 1

重要不变量

缓冲区始终恰好有 240 个条目
每个 PPU 拥有独立的缓冲区
记录不会修改真实的 PPU.vram_addr
细X单独存储
后渲染、VBlank 和预渲染不会被记录

超出范围

归档已完成的帧
替换缺失的条目
重置当前帧缓冲区
帧缓冲或不透明度掩码合成

完整示例实现

# emulator/ppu/ppu.py

# --- NEW BLOCK: EFFECTIVE STATE FOR ONE VISIBLE SCANLINE ---
@dataclass(frozen=True)
class BackgroundScanlineState:
    vram_addr: int
    fine_x: int


@dataclass
class PPU:
    ...

    # --- NEW LINE: CURRENT FRAME'S VISIBLE SCANLINE STATES ---
    current_scanline_scroll_states: list[
        BackgroundScanlineState | None
    ] = field(default_factory=lambda: [None] * 240)

    ...

    # --- NEW BLOCK: RECORD THE CURRENT VISIBLE SCANLINE ---
    def _record_visible_scanline_scroll_state(self) -> None:
        rendering_enabled = self.mask & (
            MASK_SHOW_BACKGROUND | MASK_SHOW_SPRITES
        )
        if not rendering_enabled:
            return

        if not 0 <= self.scanline < 240:
            return

        if self.cycle != 1:
            return

        visible_vram_addr = decrement_horizontal_vram_addr(
            decrement_horizontal_vram_addr(self.vram_addr)
        )

        self.current_scanline_scroll_states[self.scanline] = (
            BackgroundScanlineState(
                vram_addr=visible_vram_addr,
                fine_x=self.fine_x,
            )
        )

    def step(self, cycles: int = 1) -> None:
        ...

        for _ in range(cycles):
            self.cycle += 1
            self._step_horizontal_rendering_address()
            self._step_vertical_rendering_address()

            # --- NEW LINE: RECORD THE CURRENT SCANLINE AT DOT 1 ---
            self._record_visible_scanline_scroll_state()

            ...

运行本课

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

示例实现

完整示例实现

# emulator/ppu/ppu.py

# --- NEW BLOCK: EFFECTIVE STATE FOR ONE VISIBLE SCANLINE ---
@dataclass(frozen=True)
class BackgroundScanlineState:
    vram_addr: int
    fine_x: int


@dataclass
class PPU:
    ...

    # --- NEW LINE: CURRENT FRAME'S VISIBLE SCANLINE STATES ---
    current_scanline_scroll_states: list[
        BackgroundScanlineState | None
    ] = field(default_factory=lambda: [None] * 240)

    ...

    # --- NEW BLOCK: RECORD THE CURRENT VISIBLE SCANLINE ---
    def _record_visible_scanline_scroll_state(self) -> None:
        rendering_enabled = self.mask & (
            MASK_SHOW_BACKGROUND | MASK_SHOW_SPRITES
        )
        if not rendering_enabled:
            return

        if not 0 <= self.scanline < 240:
            return

        if self.cycle != 1:
            return

        visible_vram_addr = decrement_horizontal_vram_addr(
            decrement_horizontal_vram_addr(self.vram_addr)
        )

        self.current_scanline_scroll_states[self.scanline] = (
            BackgroundScanlineState(
                vram_addr=visible_vram_addr,
                fine_x=self.fine_x,
            )
        )

    def step(self, cycles: int = 1) -> None:
        ...

        for _ in range(cycles):
            self.cycle += 1
            self._step_horizontal_rendering_address()
            self._step_vertical_rendering_address()

            # --- NEW LINE: RECORD THE CURRENT SCANLINE AT DOT 1 ---
            self._record_visible_scanline_scroll_state()

            ...

查看测试代码test_345_record_visible_scanline_scroll_state.py

from dataclasses import FrozenInstanceError

import pytest

from emulator.ppu.ppu import (
    BackgroundScanlineState,
    MASK_SHOW_BACKGROUND,
    MASK_SHOW_SPRITES,
    PPU,
)


def test_scanline_state_is_immutable_value_data():
    """
    Objective:
    Prevent a recorded scanline from changing when later PPU state changes.
    """
    state = BackgroundScanlineState(vram_addr=5, fine_x=3)

    with pytest.raises(FrozenInstanceError):
        state.fine_x = 4


def test_new_ppu_has_240_unrecorded_scanline_entries():
    """
    Objective:
    Provide one bounded slot for every visible screen row.
    """
    ppu = PPU()

    assert len(ppu.current_scanline_scroll_states) == 240
    assert ppu.current_scanline_scroll_states == [None] * 240


def test_each_ppu_owns_an_independent_scanline_buffer():
    """
    Objective:
    Avoid shared mutable default state between emulator instances and tests.
    """
    first = PPU()
    second = PPU()

    first.current_scanline_scroll_states[0] = BackgroundScanlineState(0, 0)

    assert second.current_scanline_scroll_states[0] is None


@pytest.mark.parametrize("rendering_mask", [MASK_SHOW_BACKGROUND, MASK_SHOW_SPRITES])
def test_dot_one_records_when_either_rendering_path_is_enabled(rendering_mask):
    """
    Objective:
    Match the same PPUMASK rendering condition used by automatic v timing.
    """
    ppu = PPU()
    ppu.mask = rendering_mask
    ppu.scanline = 20
    ppu.cycle = 0
    ppu.vram_addr = 7
    ppu.fine_x = 3

    ppu.step()

    assert ppu.cycle == 1
    assert ppu.current_scanline_scroll_states[20] == BackgroundScanlineState(
        vram_addr=5,
        fine_x=3,
    )


def test_recording_uses_current_scanline_index_not_horizontal_rewind_count():
    """
    Objective:
    Keep vertical row selection independent from the two horizontal tile rewinds.
    """
    ppu = PPU()
    ppu.mask = MASK_SHOW_BACKGROUND
    ppu.scanline = 20
    ppu.cycle = 0
    ppu.vram_addr = 7

    ppu.step()

    assert ppu.current_scanline_scroll_states[18] is None
    assert ppu.current_scanline_scroll_states[19] is None
    assert ppu.current_scanline_scroll_states[20] is not None


def test_recording_rewinds_across_horizontal_nametable_boundary():
    """
    Objective:
    Interpret two prefetched tiles correctly when the rewind crosses from logical
    nametable X=1 back into logical nametable X=0.
    """
    ppu = PPU()
    ppu.mask = MASK_SHOW_BACKGROUND
    ppu.scanline = 50
    ppu.cycle = 0
    ppu.vram_addr = 0x0400 | 1

    ppu.step()

    state = ppu.current_scanline_scroll_states[50]
    assert state is not None
    assert state.vram_addr & 0x001F == 31
    assert (state.vram_addr & 0x0400) == 0


def test_recording_does_not_modify_real_ppu_vram_addr():
    """
    Objective:
    Keep the active rendering address ahead while recording a derived visible address.
    """
    ppu = PPU()
    ppu.mask = MASK_SHOW_BACKGROUND
    ppu.scanline = 80
    ppu.cycle = 0
    ppu.vram_addr = 12

    ppu.step()

    assert ppu.vram_addr == 12
    assert ppu.current_scanline_scroll_states[80] == BackgroundScanlineState(
        vram_addr=10,
        fine_x=0,
    )


def test_recording_is_disabled_when_rendering_is_disabled():
    """
    Objective:
    Do not manufacture viewport history while PPUMASK disables rendering.
    """
    ppu = PPU()
    ppu.mask = 0
    ppu.scanline = 30
    ppu.cycle = 0
    ppu.vram_addr = 7

    ppu.step()

    assert ppu.current_scanline_scroll_states[30] is None


@pytest.mark.parametrize("scanline", [240, 241, 260, 261])
def test_non_visible_scanlines_are_not_recorded(scanline):
    """
    Objective:
    Restrict the 240-entry state list to visible output rows only.
    """
    ppu = PPU()
    ppu.mask = MASK_SHOW_BACKGROUND
    ppu.scanline = scanline
    ppu.cycle = 0
    ppu.vram_addr = 7

    ppu.step()

    assert ppu.current_scanline_scroll_states == [None] * 240


def test_only_dot_one_records_the_scanline_state():
    """
    Objective:
    Prevent later fetch-address changes from replacing the visible start position.
    """
    ppu = PPU()
    ppu.mask = MASK_SHOW_BACKGROUND
    ppu.scanline = 100
    ppu.cycle = 0
    ppu.vram_addr = 7

    ppu.step()  # dot 1 records visible coarse X 5
    recorded = ppu.current_scanline_scroll_states[100]

    ppu.vram_addr = 20
    ppu.step()  # dot 2 must not overwrite the state

    assert ppu.current_scanline_scroll_states[100] == recorded

测试函数 (10)

test_scanline_state_is_immutable_value_data
test_new_ppu_has_240_unrecorded_scanline_entries
test_each_ppu_owns_an_independent_scanline_buffer
test_dot_one_records_when_either_rendering_path_is_enabled
test_recording_uses_current_scanline_index_not_horizontal_rewind_count
test_recording_rewinds_across_horizontal_nametable_boundary
test_recording_does_not_modify_real_ppu_vram_addr
test_recording_is_disabled_when_rendering_is_disabled
test_non_visible_scanlines_are_not_recorded
test_only_dot_one_records_the_scanline_state