309. Main usa el framebuffer completo

Crear main.py a partir de main_only_background.py y usar Console.render_framebuffer().

Lección 309 de 356 · tests/chapter_09_sprite_rendering/test_309_main_uses_full_framebuffer.py

Archivos involucrados

main_only_background.py
main.py

Por qué existe este paso

main_only_background.py conserva el ejecutor manual anterior que mostraba únicamente el framebuffer de fondo. Para este paso, copiar ese archivo a main.py y luego aplicar allí las modificaciones de renderizado de cuadro completo.

Console ahora expone render_framebuffer(), que devuelve fondo + sprites en un solo Framebuffer puro. El nuevo main.py debería usar esa ruta de renderizado de cuadro completo en lugar del helper anterior solo de fondo.

El archivo plantilla, main_only_background.py, muestra:

console.render_background_framebuffer()

Tras copiarlo a main.py y aplicar este paso, main.py muestra:

console.render_framebuffer()

Esto permite que el ejecutor manual de pygame muestre sprites como Mario/enemigos/objetos cuando el estado actual de la PPU contiene datos válidos de OAM, CHR y paleta de sprites.

Flujo de implementación sugerido

cp main_only_background.py main.py

Luego actualizar main.py para que esta línea:

framebuffer = console.render_background_framebuffer()

se convierta en:

framebuffer = console.render_framebuffer()

Hacer esto tanto antes de crear la ventana de pygame como después de cada paso de cuadro.

Regla importante de preservación

No eliminar main_only_background.py. Los tests anteriores del tutorial lo usan como punto de control histórico estable del ejecutor solo de fondo.

Limitación visual conocida

Los sprites pueden aparecer incorrectamente delante de tuberías/tubos. Esto es esperable por ahora porque el bit 5 de prioridad sprite/fondo se decodifica pero aún no se aplica. El siguiente trabajo planificado es una máscara de opacidad de fondo y composición con prioridad.

Comando manual

uv run python main.py

Comportamiento manual esperado

La ventana de pygame debería seguir mostrando el fondo, y los sprites deberían aparecer ahora. La prioridad visual puede seguir siendo incorrecta. El rendimiento puede seguir siendo lento porque el helper de dibujo actual de pygame es intencionadamente simple.

Fuera del alcance

máscara de opacidad de fondo
comportamiento de prioridad sprite/fondo
sprite 0 hit
sprite overflow
optimización rápida de subida de framebuffer
llamar a main() desde pytest

Ejecutar esta lección

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

Implementación de ejemplo

Archivos involucrados

main_only_background.py
main.py

Ver código del testtest_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()

Funciones de test (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