309. Main 使用完整帧缓冲

从 main_only_background.py 创建 main.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()

这样,当当前 PPU 状态包含有效的 OAM、CHR 和精灵调色板数据时,手动运行的 pygame 窗口就能显示出诸如马力欧/敌人/道具之类的精灵。

建议的实现流程

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 绘制辅助函数是特意写得很简单,性能也可能仍然较慢。

本步骤不涉及的内容

背景不透明度掩码
精灵/背景优先级行为
sprite 0 hit
sprite overflow
帧缓冲快速上传优化
从 pytest 中调用 main()

运行本课

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