Inspección del Puente: ¿Llegan los datos a Python?

Resumen

A pesar de que la PPU en C++ reporta operaciones correctas y forzamos la escritura de píxeles negros (Step 0212), la pantalla permanece blanca. Esto sugiere que los datos no están cruzando correctamente el puente Cython hacia Python, o que el renderizador de Python los está interpretando mal. Implementamos sondas tanto en C++ como en Python para rastrear el framebuffer en cada punto del pipeline.

Hallazgo crítico: El problema NO está en el puente Cython, sino en la sincronización temporal. Python estaba leyendo el framebuffer después de que C++ lo limpiara para el siguiente frame. La solución fue leer el framebuffer justo cuando se completa el frame (cuando ly_ pasa a 144, inicio de V-Blank) y hacer una copia para preservar los datos.

Concepto de Hardware: El Puente de Datos

En una arquitectura híbrida Python/C++, el flujo de datos del framebuffer sigue esta ruta:

1. C++ (PPU.cpp): Escribe índices de color (0-3) en un array uint8_t[23040].
2. Cython (ppu.pyx): Expone el array como un memoryview de Python usando get_framebuffer_ptr().
3. Python (viboy.py): Lee el memoryview y lo pasa al renderizador.
4. Python (renderer.py): Convierte los índices de color a RGB usando la paleta BGP y dibuja en Pygame.

El problema del "crimen perfecto": Tenemos evidencia de que:

• C++ confiesa: La sonda VALID CHECK: PASS (Step 0211) confirma que la lógica interna de la PPU está funcionando y las direcciones son válidas.
• La evidencia visual: La pantalla está BLANCA.
• La deducción: Si C++ está escribiendo 3 (negro) en el framebuffer (como confirmamos con el Step 0212), pero Pygame dibuja 0 (blanco), entonces los datos se están perdiendo o corrompiendo en el puente entre C++ y Python.

La solución: Interrogar al mensajero. Vamos a inspeccionar los datos justo cuando llegan a Python, antes de que el renderizador los toque. Si Python dice "Recibí un 3", entonces el problema está en renderer.py (la paleta o el dibujo). Si Python dice "Recibí un 0", entonces el problema está en Cython (estamos leyendo la memoria equivocada o una copia vacía).

Fuente: Metodología de depuración de sistemas híbridos - "Data Probe" debugging en interfaces C++/Python.

Implementación

Se implementaron sondas de diagnóstico en múltiples puntos del pipeline para rastrear el framebuffer desde C++ hasta Python. Las sondas revelaron que el problema era de sincronización temporal, no de integridad de datos.

Sondas en C++ (PPU.cpp)

Se añadieron tres sondas en C++ para verificar el framebuffer en diferentes momentos:

1. [C++ WRITE PROBE]: Justo después de escribir en el framebuffer (línea 0, píxel 0). Confirma que el valor se escribe correctamente.
2. [C++ BEFORE CLEAR PROBE]: Justo antes de limpiar el framebuffer (cuando ly_ > 153). Verifica que el framebuffer contiene los datos correctos antes de limpiarse.
3. [C++ AFTER CLEAR PROBE]: Justo después de limpiar el framebuffer. Confirma que la limpieza funciona correctamente.

Modificación en src/viboy.py

Se modificó el bucle principal para leer el framebuffer en el momento correcto (cuando ly_ == 144, inicio de V-Blank) y hacer una copia para preservar los datos:

# --- Step 0213: Leer framebuffer justo después de línea 143 ---
# Leer el framebuffer justo después de completar la línea 143
# (última línea visible), antes de que se avance a la línea 144
# y antes de que se limpie para el siguiente frame.
if self._ppu is not None:
    current_ly = self._ppu.ly
    if current_ly == 144:  # Inicio de V-Blank, frame completo
        # CRÍTICO: Hacer una COPIA del framebuffer porque el memoryview
        # es una vista de la memoria. Si el framebuffer se limpia después,
        # la vista reflejará los valores limpios. Necesitamos preservar
        # los datos del frame completo.
        fb_view = self._ppu.framebuffer
        framebuffer_to_render = bytes(fb_view)  # Copia los datos
        
        # Sonda de diagnóstico
        if not self._debug_frame_printed:
            p0 = framebuffer_to_render[0]
            p8 = framebuffer_to_render[8]
            mid = framebuffer_to_render[23040 // 2]
            print(f"\n--- [PYTHON DATA PROBE] ---")
            print(f"Frame completo (LY=144), framebuffer leído (COPIA):")
            print(f"Pixel 0 (0,0): {p0} (Esperado: 3)")
            print(f"Pixel 8 (8,0): {p8}")
            print(f"Pixel Center: {mid}")
            print(f"---------------------------\n")
            self._debug_frame_printed = True

Resultados de las Sondas

Las sondas revelaron el problema exacto:

• [C++ WRITE PROBE]: Valor escrito: 3, Valor leído: 3 ✅
• [C++ BEFORE CLEAR PROBE]: Pixel 0: 3, Pixel 8: 3, Pixel Center: 3 ✅
• [C++ AFTER CLEAR PROBE]: Pixel 0: 0 ✅ (limpieza correcta)
• [PYTHON DATA PROBE] (antes de la solución): Pixel 0: 0 ❌ (leído después de limpiar)

Conclusión: El framebuffer se estaba limpiando antes de que Python lo leyera. La solución fue leer el framebuffer cuando ly_ == 144 (inicio de V-Blank) y hacer una copia para preservar los datos.

Lógica de la Sonda

La sonda lee tres píxeles estratégicos del framebuffer:

• Pixel 0 (0,0): El primer píxel de la pantalla. Si el Step 0212 está activo, debería ser 3 (Negro).
• Pixel 8 (8,0): El primer píxel del segundo tile. Si el patrón de rayas del Step 0212 está activo, debería ser 0 (Blanco) o 3 (Negro) dependiendo del patrón.
• Pixel Center: Un píxel en el centro de la pantalla (índice 11520) para verificar que los datos están presentes en toda la pantalla.

Análisis del resultado:

• Si ves Pixel 0: 3: ¡Los datos llegan bien! El culpable es src/gpu/renderer.py (probablemente la paleta o la conversión a superficie Pygame).
• Si ves Pixel 0: 0: ¡Houston, tenemos un problema en Cython! Estamos leyendo un buffer vacío o desconectado del real.

Archivos Afectados

• src/core/cpp/PPU.cpp - Añadidas tres sondas de diagnóstico para rastrear el framebuffer en C++ (escritura, antes de limpiar, después de limpiar)
• src/viboy.py - Modificado el bucle principal para leer el framebuffer cuando ly_ == 144 (inicio de V-Blank) y hacer una copia para preservar los datos

Tests y Verificación

Recompilación requerida: Este cambio requiere recompilar el módulo C++ porque añadimos sondas en PPU.cpp.

Recompilación del módulo C++:

python setup.py build_ext --inplace
# O usando el script de PowerShell:
.\rebuild_cpp.ps1

Ejecución del emulador:

python main.py roms/tetris.gb

Resultado observado: Las sondas mostraron:

--- [C++ WRITE PROBE] ---
Después de escribir en framebuffer[0]:
Valor escrito: 3
Valor leído: 3
Framebuffer ptr: 00000170F46C9E00
Framebuffer size: 23040
---------------------------

--- [C++ BEFORE CLEAR PROBE] ---
Justo ANTES de limpiar framebuffer (ly_ > 153):
Pixel 0 (0,0): 3 (Esperado: 3)
Pixel 8 (8,0): 3
Pixel Center (11520): 3
Framebuffer ptr: 00000170F46C9E00
---------------------------

--- [C++ AFTER CLEAR PROBE] ---
Justo DESPUÉS de limpiar framebuffer:
Pixel 0 (0,0): 0 (Esperado: 0)
---------------------------

--- [PYTHON DATA PROBE] ---
Frame completo (LY=144), framebuffer leído (COPIA):
Pixel 0 (0,0): 3 (Esperado: 3)  ✅
Pixel 8 (8,0): 3
Pixel Center: 3
---------------------------

Interpretación:

• Problema identificado: Python estaba leyendo el framebuffer después de que C++ lo limpiara para el siguiente frame. El memoryview es una vista de la memoria, por lo que refleja los valores actuales del framebuffer, no los valores del frame anterior.
• Solución implementada: Leer el framebuffer cuando ly_ == 144 (inicio de V-Blank, frame completo) y hacer una copia usando bytes(fb_view) para preservar los datos antes de que se limpien.
• Resultado: La sonda Python ahora muestra Pixel 0: 3, confirmando que los datos se leen correctamente cuando se capturan en el momento adecuado.

Validación de módulo compilado C++: El módulo C++ se recompiló exitosamente con las sondas de diagnóstico. Las sondas confirman que:

• C++ escribe correctamente en el framebuffer (valor 3).
• El framebuffer mantiene los datos correctos hasta antes de limpiarse.
• La limpieza funciona correctamente (valor 0 después de limpiar).
• Python puede leer los datos correctos cuando se capturan en el momento adecuado.

Fuentes Consultadas

• Metodología de depuración de sistemas híbridos: "Data Probe" debugging en interfaces C++/Python
• Cython Documentation: Memory Views and Zero-Copy Arrays
• Pan Docs: "PPU Framebuffer" - Estructura del buffer de píxeles

Integridad Educativa

Próximos Pasos

• [x] Identificar el problema de sincronización temporal
• [x] Implementar lectura del framebuffer en el momento correcto (LY=144)
• [x] Hacer copia del framebuffer para preservar los datos
• [ ] Modificar el renderer para usar el framebuffer copiado (si es necesario)
• [ ] Verificar que la pantalla muestre los píxeles negros correctamente
• [ ] Restaurar la lógica de renderizado normal (sin forzar píxeles negros)