318. Выравнивание кадров в main

Ограничиваем цикл ручного интерфейса скоростью NES NTSC.

Урок 318 из 356 · tests/chapter_10_performance/test_318_main_frame_pacing.py

Файл для обновления

main.py

Зачем нужен этот шаг

После более быстрой загрузки framebuffer в 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

Почему не делать sleep в Console/CPU/PPU? Ядро эмулятора отвечает за детерминированные переходы эмулируемого состояния. Выравнивание по реальному времени — это политика интерфейса, поэтому спать должен только main.py.

Распространённое заблуждение

Выравнивание кадров не исправляет точность по тактам CPU и не делает медленную эмуляцию быстрее. Оно лишь не позволяет достаточно быстрой эмуляции работать быстрее целевого оборудования.

Текущий ручной эталон

Продолжайте использовать локальный, предоставленный пользователем MarioBros.nes для этого шага по производительности. Проверка на Super Mario Bros. откладывается до реализации sprite 0 hit.

Почему тесты формы исходного кода? Автоматические тесты не должны вызывать main(), реально засыпать, открывать pygame или требовать коммерческий ROM. Эти тесты проверяют структуру выравнивания без запуска ручного цикла.

Совместимость в будущем

Шаг 356 заменяет форму исходного кода с относительным sleep из этого урока на выравнивание по абсолютному дедлайну. Когда обнаруживается эта полная замена, пропускаются только шесть устаревших утверждений формы исходного кода ниже. Устойчивая граница интерфейс/ядро и утверждения об одном эмулируемом кадре за проход цикла остаются активными, пока тест 356 проверяет новый контракт. Не добавляйте в main.py мёртвый код совместимости с wait_time или time.sleep.

Вне рамок

точность по тактам CPU при переходе через страницу/ветвлении
sprite 0 hit
проверка на Super Mario Bros.
оптимизация рендеринга pygame (завершена на предыдущем шаге)
вызов main() из pytest

Запустить этот урок

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