318. 主循环帧节奏控制

将手动前端循环限制在 NES NTSC 速度。

第 318 / 356 · tests/chapter_10_performance/test_318_main_frame_pacing.py

需要更新的文件

main.py

为什么需要这一步

在采用了更快的 pygame 帧缓冲上传方式以及可选的 PyPy 启动脚本之后，手动运行的模拟器可能会比真实 NES 运行得更快。在教程开发过程中，未加限制的路径大约达到了 90-120 FPS。

运行得更快是有用的性能证据，但这会让游戏玩法、动画和输入时序都变得过快。当一帧提前完成时，前端应当等待。

关键术语：帧节奏帧节奏是指当模拟出的一帧比目标的实际时钟时长更快完成时，延迟其呈现的做法。

目标 NTSC 时序

NES_NTSC_FPS = 60.0988
TARGET_FRAME_SECONDS = 1.0 / NES_NTSC_FPS

一个目标帧大约是

16.64 milliseconds

示例实现

# --- NEW BLOCK: NES FRAME-TIME TARGET ---
NES_NTSC_FPS = 60.0988
TARGET_FRAME_SECONDS = 1.0 / NES_NTSC_FPS
# --- END NEW BLOCK ---

...

while running:
    # --- NEW LINE: START THIS FRAME'S TIMER ---
    frame_start_time = time.perf_counter()
    # --- END NEW LINE ---

    for event in pygame.event.get():
        ...

    executed = console.step_until_next_frame()
    framebuffer = console.render_framebuffer()
    draw_framebuffer(window, framebuffer, SCALE)
    pygame.display.flip()

    # --- NEW BLOCK: WAIT FOR THE UNUSED FRAME BUDGET ---
    # Sleep only for the unused part of this frame's time budget.
    frame_end_time = time.perf_counter()
    frame_elapsed_time = frame_end_time - frame_start_time
    wait_time = TARGET_FRAME_SECONDS - frame_elapsed_time

    if wait_time > 0:
        time.sleep(wait_time)
    # --- END NEW BLOCK ---

    # --- UPDATED BLOCK: MEASURE FPS AFTER PACING ---
    # Measure FPS after sleeping so the report shows paced gameplay speed.
    frames_since_last_report += 1
    now = time.perf_counter()
    elapsed = now - last_fps_report_time

    if elapsed >= FPS_REPORT_INTERVAL_SECONDS:
        fps = frames_since_last_report / elapsed
        print(f"fps={fps:.1f}")
        frames_since_last_report = 0
        last_fps_report_time = now
    # --- END UPDATED BLOCK ---

重要的不变量

Fast frame:
    frame_elapsed_time < TARGET_FRAME_SECONDS
    wait_time > 0
    frontend sleeps for the remaining budget

Slow frame:
    frame_elapsed_time >= TARGET_FRAME_SECONDS
    wait_time <= 0
    frontend does not sleep

为什么不在 Console/CPU/PPU 中休眠？模拟器核心负责确定性的模拟状态转换。基于实际时钟的节奏控制属于前端策略，因此只有 main.py 应当休眠。

常见的误解

帧节奏并不能修正 CPU 周期精度，也不会让缓慢的模拟变得更快。它只是防止运行速度足够快的模拟超过目标硬件的速度。

当前手动参考

在这一性能步骤中，继续使用本地由用户自行提供的 MarioBros.nes。对《超级马里奥兄弟》的验证要延后到实现精灵 0 命中之后再进行。

为什么要做源码结构测试？自动化测试不得调用 main()、进行真实的休眠、打开 pygame，也不得要求使用商业 ROM。这些测试只验证节奏控制的结构，而不实际运行手动循环。

未来的兼容性

步骤 356 会用基于绝对截止时间的节奏控制，替换本课中基于相对休眠的源码结构。当检测到这种完全替换时，下面这六条过时的源码结构断言会被跳过。而那些持久有效的前端/核心边界以及“每次循环只模拟一帧”的断言仍然保持生效，由测试 356 来验证新的约定。不要在 main.py 中添加已废弃的 wait_time 或 time.sleep 兼容代码。

本步骤范围之外

CPU 分支/跨页周期精度
精灵 0 命中
《超级马里奥兄弟》验证
pygame 渲染优化（已在上一步完成）
从 pytest 中调用 main()

运行本课

uv run pytest tests/chapter_10_performance/test_318_main_frame_pacing.py -v

示例实现

# --- NEW BLOCK: NES FRAME-TIME TARGET ---
NES_NTSC_FPS = 60.0988
TARGET_FRAME_SECONDS = 1.0 / NES_NTSC_FPS
# --- END NEW BLOCK ---

...

while running:
    # --- NEW LINE: START THIS FRAME'S TIMER ---
    frame_start_time = time.perf_counter()
    # --- END NEW LINE ---

    for event in pygame.event.get():
        ...

    executed = console.step_until_next_frame()
    framebuffer = console.render_framebuffer()
    draw_framebuffer(window, framebuffer, SCALE)
    pygame.display.flip()

    # --- NEW BLOCK: WAIT FOR THE UNUSED FRAME BUDGET ---
    # Sleep only for the unused part of this frame's time budget.
    frame_end_time = time.perf_counter()
    frame_elapsed_time = frame_end_time - frame_start_time
    wait_time = TARGET_FRAME_SECONDS - frame_elapsed_time

    if wait_time > 0:
        time.sleep(wait_time)
    # --- END NEW BLOCK ---

    # --- UPDATED BLOCK: MEASURE FPS AFTER PACING ---
    # Measure FPS after sleeping so the report shows paced gameplay speed.
    frames_since_last_report += 1
    now = time.perf_counter()
    elapsed = now - last_fps_report_time

    if elapsed >= FPS_REPORT_INTERVAL_SECONDS:
        fps = frames_since_last_report / elapsed
        print(f"fps={fps:.1f}")
        frames_since_last_report = 0
        last_fps_report_time = now
    # --- END UPDATED BLOCK ---

查看测试代码test_318_main_frame_pacing.py

import inspect
from pathlib import Path

import pytest

import main


def _uses_absolute_deadline_pacing() -> bool:
    """Detect the complete Step 356 replacement without changing production code."""
    source = inspect.getsource(main.main)
    compact_source = "".join(source.split())

    return (
        hasattr(main, "TARGET_DISPLAY_FPS")
        and hasattr(main, "TARGET_FRAME_SECONDS")
        and "next_frame_deadline" in compact_source
        and "whiletime.perf_counter()<next_frame_deadline:" in compact_source
        and "next_frame_deadline+=TARGET_FRAME_SECONDS" in compact_source
    )


legacy_relative_sleep_pacing_only = pytest.mark.skipif(
    _uses_absolute_deadline_pacing(),
    reason="Step 356 supersedes relative-sleep pacing with absolute deadlines",
)


@legacy_relative_sleep_pacing_only
def test_main_defines_ntsc_nes_fps_target():
    """
    Objective:
    Name the approximate NTSC NES frame rate explicitly instead of using an
    unexplained sleep duration.
    """
    assert hasattr(main, "NES_NTSC_FPS")
    assert main.NES_NTSC_FPS == pytest.approx(60.0988)


@legacy_relative_sleep_pacing_only
def test_main_derives_target_frame_seconds_from_nes_fps():
    """
    Objective:
    Keep FPS and frame-duration constants connected by one clear invariant.
    """
    assert hasattr(main, "TARGET_FRAME_SECONDS")
    assert main.TARGET_FRAME_SECONDS == pytest.approx(1.0 / main.NES_NTSC_FPS)
    assert main.TARGET_FRAME_SECONDS == pytest.approx(0.016639, abs=0.000001)


@legacy_relative_sleep_pacing_only
def test_main_starts_frame_timer_before_emulation_work():
    """
    Objective:
    The frame budget should include event handling, emulation, rendering, and pygame
    display work.
    """
    source = inspect.getsource(main.main)

    start_index = source.index("frame_start_time = time.perf_counter()")
    # Search after the frame timer so the earlier initial framebuffer used to size
    # the pygame window is not mistaken for the per-frame render call.
    step_index = source.index("console.step_until_next_frame()", start_index)
    render_index = source.index("console.render_framebuffer()", step_index)
    flip_index = source.index("pygame.display.flip()", render_index)

    assert start_index < step_index < render_index < flip_index


@legacy_relative_sleep_pacing_only
def test_main_computes_remaining_time_after_display_work():
    """
    Objective:
    Sleep should use only the unused part of the target frame duration.
    """
    source = inspect.getsource(main.main)

    flip_index = source.index("pygame.display.flip()")
    end_index = source.index("frame_end_time = time.perf_counter()")
    elapsed_index = source.index(
        "frame_elapsed_time = frame_end_time - frame_start_time"
    )
    wait_index = source.index(
        "wait_time = TARGET_FRAME_SECONDS - frame_elapsed_time"
    )

    assert flip_index < end_index < elapsed_index < wait_index


@legacy_relative_sleep_pacing_only
def test_main_sleeps_only_when_frame_finishes_early():
    """
    Objective:
    Negative wait times represent slow frames and must never be passed to
    time.sleep().
    """
    source = inspect.getsource(main.main)

    condition_index = source.index("if wait_time > 0:")
    sleep_index = source.index("time.sleep(wait_time)")

    assert condition_index < sleep_index


@legacy_relative_sleep_pacing_only
def test_main_measures_reported_fps_after_frame_pacing_sleep():
    """
    Objective:
    The terminal FPS signal should show paced gameplay speed, not uncapped raw
    throughput.
    """
    source = inspect.getsource(main.main)

    sleep_index = source.index("time.sleep(wait_time)")
    count_index = source.index("frames_since_last_report += 1")
    fps_time_index = source.index("now = time.perf_counter()", count_index)

    assert sleep_index < count_index < fps_time_index


def test_frame_pacing_stays_in_main_not_emulator_core():
    """
    Objective:
    Wall-clock waiting is frontend policy. Emulator core modules must remain free
    from time.sleep().
    """
    core_files = [
        Path("emulator/console.py"),
        Path("emulator/cpu/cpu.py"),
        Path("emulator/ppu/ppu.py"),
        Path("emulator/rendering/frame_compositor.py"),
    ]

    for file_path in core_files:
        assert "time.sleep" not in file_path.read_text()


def test_main_still_uses_one_emulated_ppu_frame_per_frontend_iteration():
    """
    Objective:
    Frame pacing delays presentation; it should not replace or multiply the existing
    emulated frame-step mechanism.
    """
    source = inspect.getsource(main.main)

    assert source.count("console.step_until_next_frame()") == 1

测试函数 (8)

test_main_defines_ntsc_nes_fps_target
test_main_derives_target_frame_seconds_from_nes_fps
test_main_starts_frame_timer_before_emulation_work
test_main_computes_remaining_time_after_display_work
test_main_sleeps_only_when_frame_finishes_early
test_main_measures_reported_fps_after_frame_pacing_sleep
test_frame_pacing_stays_in_main_not_emulator_core
test_main_still_uses_one_emulated_ppu_frame_per_frontend_iteration