315. 主循环 FPS 计数器

为 main.py 添加一个简单的周期性 FPS 计数器。

第 315 / 356 · tests/chapter_10_performance/test_315_main_fps_counter.py

需要更新的文件

main.py

为什么需要这一步

在优化 pygame 渲染或模拟器速度之前，手动运行器应当在终端中显示一个简单的端到端 FPS 信号。

该 FPS 计数器应测量完整的手动帧路径

Console.step_until_next_frame()
Console.render_framebuffer()
draw_framebuffer(...)
pygame.display.flip()

建议的实现示例

import time

FPS_REPORT_INTERVAL_SECONDS = 1.0

...

running = True
last_fps_report_time = time.perf_counter()
frames_since_last_report = 0

while running:
    ...

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

    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

重要提示

这里刻意保持简单。它不会将模拟时间与渲染时间区分开来，只是在开始优化工作之前，在终端上提供一个可见的信号。

为什么要做源码结构测试？main.py 会打开 pygame 并运行一个手动循环。自动化测试不得调用 main()、打开窗口，也不得要求使用商业 ROM。

本步骤范围之外

优化 pygame 绘制
帧节奏 / 速度上限
对各个子系统分别进行性能分析
启动 PyPy
从 pytest 中调用 main()

运行本课

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

示例实现

建议的实现示例

import time

FPS_REPORT_INTERVAL_SECONDS = 1.0

...

running = True
last_fps_report_time = time.perf_counter()
frames_since_last_report = 0

while running:
    ...

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

    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

查看测试代码test_315_main_fps_counter.py

import inspect

import main


def test_main_imports_time_for_fps_measurement():
    """
    Objective:
    FPS reporting should use a monotonic high-resolution timer from the standard
    library.
    """
    source = inspect.getsource(main)

    assert "import time" in source


def test_main_defines_one_second_fps_report_interval():
    """
    Objective:
    The first FPS counter should be intentionally simple and report about once per
    second.
    """
    assert hasattr(main, "FPS_REPORT_INTERVAL_SECONDS")
    assert main.FPS_REPORT_INTERVAL_SECONDS == 1.0


def test_main_initializes_fps_counter_state_before_loop():
    """
    Objective:
    main.py should track when the previous report happened and how many frames have
    completed since then.
    """
    source = inspect.getsource(main.main)

    assert "last_fps_report_time = time.perf_counter()" in source
    assert "frames_since_last_report = 0" in source


def test_main_counts_frames_after_display_flip():
    """
    Objective:
    The FPS counter should measure the full manual frame path, including pygame
    drawing and display flip.
    """
    source = inspect.getsource(main.main)

    flip_index = source.index("pygame.display.flip()")
    count_index = source.index("frames_since_last_report += 1")

    assert flip_index < count_index


def test_main_prints_fps_when_one_second_interval_elapsed():
    """
    Objective:
    main.py should compute frames / elapsed time and print a small terminal signal.
    """
    source = inspect.getsource(main.main)

    assert "elapsed = now - last_fps_report_time" in source
    assert "elapsed >= FPS_REPORT_INTERVAL_SECONDS" in source
    assert "fps = frames_since_last_report / elapsed" in source
    assert "fps=" in source


def test_main_resets_fps_counter_after_report():
    """
    Objective:
    After printing a report, the next one-second window should start fresh.
    """
    source = inspect.getsource(main.main)

    assert "frames_since_last_report = 0" in source
    assert "last_fps_report_time = now" in source


def test_fps_counter_stays_in_manual_frontend_not_emulator_core():
    """
    Objective:
    FPS reporting is manual/frontend observability. The emulator core should not
    import time for display reporting.
    """
    core_files = [
        "emulator/console.py",
        "emulator/cpu/cpu.py",
        "emulator/ppu/ppu.py",
        "emulator/rendering/frame_compositor.py",
    ]

    for file_path in core_files:
        source = open(file_path, encoding="utf-8").read()
        assert "import time" not in source

测试函数 (7)

test_main_imports_time_for_fps_measurement
test_main_defines_one_second_fps_report_interval
test_main_initializes_fps_counter_state_before_loop
test_main_counts_frames_after_display_flip
test_main_prints_fps_when_one_second_interval_elapsed
test_main_resets_fps_counter_after_report
test_fps_counter_stays_in_manual_frontend_not_emulator_core