⚠️ Clean-Room / Educativo

Este proyecto es educativo y Open Source. No se copia código de otros emuladores. Implementación basada únicamente en documentación técnica y tests permitidas.

Verificación Extendida y Monitor de Framebuffer

Fecha: 2025-12-25 Step ID: 0304 Estado: DRAFT

Resumen

Implementación de monitores de framebuffer con flags de activación para rastrear qué índices tiene el framebuffer en cada frame y detectar cuándo cambia de tener solo índices 0 a tener índices 1 o 2. Los monitores están preparados pero desactivados por defecto, y solo se activarán si la verificación visual extendida (10-15 minutos) confirma que las rayas verdes persisten después de las correcciones del Step 0303.

Objetivo: Verificar que las correcciones de paleta eliminaron las rayas verdes durante una sesión extendida. Si las rayas aparecen, los monitores permitirán identificar cuándo y por qué cambia el framebuffer.

Concepto de Hardware

Framebuffer e Índices de Color

El framebuffer contiene índices de color (0-3), no colores RGB directamente. Estos índices se mapean a colores usando una paleta. Si el framebuffer cambia de tener solo índices 0 a tener índices 1 o 2, significa que la PPU está escribiendo diferentes valores en el framebuffer.

En condiciones normales, el framebuffer debería tener principalmente índices 0 (blanco) cuando no hay gráficos, o una mezcla de índices 0-3 cuando hay gráficos renderizados. Si aparecen rayas verdes después de unos minutos, significa que el framebuffer está recibiendo valores 1 o 2 que se están mapeando incorrectamente a verde (en lugar de gris).

Rastreo de Framebuffer

Monitorear el contenido del framebuffer permite identificar cuándo y dónde se escriben valores específicos. Los monitores deben ser eficientes para no afectar el rendimiento, por lo que solo rastrean cuando hay cambios o a intervalos regulares (cada 1000 frames).

Fuente: Pan Docs - "Framebuffer", "Background Palette (BGP)"

Implementación

Se implementaron dos monitores de framebuffer con flags de activación:

Monitor en Python (renderer.py)

Monitor [FRAMEBUFFER-INDEX-TRACE] que rastrea qué índices tiene el framebuffer en cada frame:

  • Cuenta cuántos píxeles tienen cada índice (0, 1, 2, 3)
  • Detecta si hay valores no-cero (1, 2 o 3)
  • Registra información solo cuando hay cambios o cada 1000 frames
  • Limita a 100 registros para no saturar los logs

Flag de activación: self._framebuffer_trace_enabled = False (cambiar a True si se necesitan logs)

Monitor en C++ (PPU.cpp)

Monitor [FRAMEBUFFER-DETAILED] que monitorea el framebuffer desde el lado C++:

  • Rastrea la línea central (LY=72) cada 1000 frames
  • Cuenta píxeles no-cero en la línea central
  • Muestra una muestra de los primeros 32 píxeles
  • Limita a 100 registros para no saturar los logs

Flag de activación: ENABLE_FRAMEBUFFER_DETAILED_TRACE = false (cambiar a true si se necesitan logs)

Decisiones de Diseño

  • Flags de activación: Los monitores están desactivados por defecto para no afectar el rendimiento. Solo se activan si la verificación visual confirma que las rayas aparecen.
  • Límites de registro: Se limitan a 100 registros para evitar saturar el contexto y los logs.
  • Intervalos de rastreo: Solo rastrean cada 1000 frames o cuando hay cambios, para minimizar el overhead.
  • Línea central: El monitor C++ rastrea la línea central (LY=72) como muestra representativa del framebuffer.

Archivos Afectados

  • src/gpu/renderer.py - Implementación del monitor [FRAMEBUFFER-INDEX-TRACE] con flag de activación
  • src/core/cpp/PPU.cpp - Implementación del monitor [FRAMEBUFFER-DETAILED] con flag de activación
  • INSTRUCCIONES_VERIFICACION_STEP_0304.md - Instrucciones para la verificación visual extendida

Tests y Verificación

Verificación Visual Extendida: Pendiente de ejecución. El usuario debe ejecutar el emulador durante 10-15 minutos para verificar si las rayas verdes aparecen después de las correcciones del Step 0303.

Instrucciones: Ver archivo INSTRUCCIONES_VERIFICACION_STEP_0304.md para los pasos detallados de verificación.

Monitores: Los monitores están implementados pero desactivados por defecto. Solo se activarán si la verificación visual confirma que las rayas aparecen.

Fuentes Consultadas

  • Pan Docs: "Framebuffer", "Background Palette (BGP)"
  • Step 0303: Corrección de Paleta Debug Índices 1 y 2

Integridad Educativa

Lo que Entiendo Ahora

  • Framebuffer e índices: El framebuffer contiene índices de color (0-3), no colores RGB. Estos índices se mapean a colores usando una paleta.
  • Monitoreo eficiente: Los monitores deben ser eficientes para no afectar el rendimiento. Solo rastrean cuando hay cambios o a intervalos regulares.
  • Flags de activación: Los monitores están desactivados por defecto y solo se activan si se necesitan, para evitar overhead innecesario.

Lo que Falta Confirmar

  • Verificación visual: ¿Las correcciones del Step 0303 eliminaron las rayas verdes? Pendiente de verificación extendida (10-15 minutos).
  • Origen de valores 1 y 2: Si las rayas aparecen, los monitores ayudarán a identificar cuándo y por qué el framebuffer cambia de tener solo índices 0 a tener índices 1 o 2.

Hipótesis y Suposiciones

Hipótesis: Las correcciones del Step 0303 deberían eliminar las rayas verdes, ya que todas las paletas de debug ahora usan grises verdaderos en lugar de verde para los índices 1 y 2. Si las rayas persisten, significa que hay otro origen del problema (posiblemente en la PPU C++ o en cómo se escriben los valores en el framebuffer).

Próximos Pasos

  • [ ] Ejecutar verificación visual extendida (10-15 minutos) con Pokémon Red
  • [ ] Registrar observaciones: ¿Aparecen rayas verdes? ¿Cuándo? ¿Cómo se ven?
  • [ ] Si NO aparecen rayas: Documentar éxito y continuar con otras funcionalidades
  • [ ] Si SÍ aparecen rayas: Activar monitores y ejecutar con logs capturados
  • [ ] Analizar logs (si se capturaron) para identificar cuándo y por qué cambia el framebuffer
  • [ ] Generar resumen ejecutivo con hallazgos y conclusiones
  • [ ] Step 0305 (si se necesita): Investigar código de PPU C++ para identificar dónde se escriben valores 1 o 2