309. Main использует полный фреймбуфер

Создать main.py из main_only_background.py и использовать Console.render_framebuffer().

Урок 309 из 356 · tests/chapter_09_sprite_rendering/test_309_main_uses_full_framebuffer.py

Задействованные файлы

main_only_background.py
main.py

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

main_only_background.py сохраняет предыдущий сценарий ручного запуска, который отображал только фреймбуфер фона. Для этого шага скопируйте этот файл в main.py, а затем примените в нём изменения для отрисовки полного кадра.

Теперь Console предоставляет render_framebuffer(), который возвращает фон и спрайты в одном чистом Framebuffer. Новый main.py должен использовать этот путь отрисовки полного кадра вместо более старой вспомогательной функции, работающей только с фоном.

Файл-шаблон main_only_background.py отображает:

console.render_background_framebuffer()

После копирования его в main.py и применения этого шага main.py отображает:

console.render_framebuffer()

Это позволяет ручному сценарию pygame показывать спрайты вроде Mario/врагов/предметов, когда текущее состояние PPU содержит корректные данные OAM, CHR и палитр спрайтов.

Предлагаемый порядок реализации

cp main_only_background.py main.py

Затем измените main.py так, чтобы эта строка:

framebuffer = console.render_background_framebuffer()

стала:

framebuffer = console.render_framebuffer()

Сделайте это и перед созданием окна pygame, и после каждого шага кадра.

Важное правило сохранения

Не удаляйте main_only_background.py. Более старые тесты руководства используют его как стабильную историческую контрольную точку для сценария, отображающего только фон.

Известное визуальное ограничение

Спрайты могут некорректно отображаться перед трубами/трубками. На данный момент это ожидаемо, потому что бит 5 приоритета спрайт/фон декодирован, но ещё не применяется. Следующая запланированная работа — маска непрозрачности фона и композитинг с учётом приоритета.

Команда для ручного запуска

uv run python main.py

Ожидаемое поведение при ручном запуске

Окно pygame должно по-прежнему показывать фон, а спрайты теперь должны появляться. Визуальный приоритет пока может быть неверным. Производительность пока может быть низкой, потому что текущая вспомогательная функция отрисовки pygame намеренно проста.

Вне рамок этого шага

маска непрозрачности фона
поведение приоритета спрайт/фон
попадание спрайта 0
переполнение спрайтов
оптимизация быстрой загрузки фреймбуфера
вызов main() из pytest

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

uv run pytest tests/chapter_09_sprite_rendering/test_309_main_uses_full_framebuffer.py -v

Пример реализации

Задействованные файлы

main_only_background.py
main.py

Показать код тестаtest_309_main_uses_full_framebuffer.py

import inspect
from pathlib import Path

import main


def test_main_uses_console_render_framebuffer_for_initial_window_size():
    """
    Objective:
    The initial framebuffer used for window dimensions should come from the full
    background+sprites render path.
    """
    source = inspect.getsource(main.main)

    assert "framebuffer = console.render_framebuffer()" in source


def test_main_no_longer_calls_background_only_render_helper():
    """
    Objective:
    main.py should display the full framebuffer, while main_only_background.py keeps
    the historical background-only debug path.
    """
    source = inspect.getsource(main.main)

    assert "render_background_framebuffer" not in source


def test_main_still_steps_frame_before_redrawing_full_framebuffer():
    """
    Objective:
    Each visual update should advance emulation by one PPU frame, then render the
    current full framebuffer.
    """
    source = inspect.getsource(main.main)

    step_index = source.index("console.step_until_next_frame()")
    render_index = source.rindex("console.render_framebuffer()")

    assert step_index < render_index


def test_main_still_draws_framebuffer_with_existing_pygame_helper():
    """
    Objective:
    This step changes the framebuffer source, not the pygame drawing mechanism.
    """
    source = inspect.getsource(main.main)
    full_source = Path("main.py").read_text()

    assert "from tools.show_framebuffer import draw_framebuffer" in full_source
    assert "draw_framebuffer(window, framebuffer, SCALE)" in source
    assert "pygame.display.flip()" in source


def test_main_keeps_keyboard_controller_mapping_after_full_framebuffer_switch():
    """
    Objective:
    Switching to full-frame rendering should not remove controller input handling.
    """
    source = inspect.getsource(main.main)

    assert "pygame.KEYDOWN" in source
    assert "pygame.KEYUP" in source
    assert "handle_key_event(cpu_bus.controller_1, event.key, True)" in source
    assert "handle_key_event(cpu_bus.controller_1, event.key, False)" in source


def test_main_keeps_error_reporting_after_full_framebuffer_switch():
    """
    Objective:
    Manual ROM execution should still print emulator context before re-raising
    unexpected errors.
    """
    source = inspect.getsource(main.main)

    assert "except Exception as error" in source
    assert "print_emulation_error(error, console)" in source
    assert "raise" in source


def test_main_keeps_manual_exit_paths_after_full_framebuffer_switch():
    """
    Objective:
    The manual pygame loop should still support window close and Ctrl+C.
    """
    source = inspect.getsource(main.main)

    assert "pygame.QUIT" in source
    assert "running = False" in source
    assert "except KeyboardInterrupt" in source
    assert "Stopped by user" in source


def test_main_full_framebuffer_step_keeps_pygame_outside_emulator_core():
    """
    Objective:
    pygame remains a manual/frontend dependency only. Full-frame rendering in
    Console/rendering modules must stay pure.
    """
    core_files = [
        Path("emulator/console.py"),
        Path("emulator/rendering/frame_compositor.py"),
        Path("emulator/rendering/sprite_renderer.py"),
        Path("emulator/rendering/ppu_background_renderer.py"),
    ]

    for file_path in core_files:
        assert "import pygame" not in file_path.read_text()

Тестовые функции (8)

test_main_uses_console_render_framebuffer_for_initial_window_size
test_main_no_longer_calls_background_only_render_helper
test_main_still_steps_frame_before_redrawing_full_framebuffer
test_main_still_draws_framebuffer_with_existing_pygame_helper
test_main_keeps_keyboard_controller_mapping_after_full_framebuffer_switch
test_main_keeps_error_reporting_after_full_framebuffer_switch
test_main_keeps_manual_exit_paths_after_full_framebuffer_switch
test_main_full_framebuffer_step_keeps_pygame_outside_emulator_core