⚠️ 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.

Corrección de Paleta Debug Índices 1 y 2

Fecha: 2025-12-25 Step ID: 0303 Estado: VERIFIED

Resumen

Corrección de todas las paletas de debug en el renderer que usan colores verdes para los índices 1 y 2, cambiándolos a grises verdaderos para eliminar las rayas verdes que aparecen cuando el framebuffer contiene valores 1 o 2. Se identificaron y corrigieron 4 ubicaciones donde se definen paletas con valores verdes.

Resultado: Se corrigieron los valores de los índices 1 y 2 en todas las paletas de debug, cambiando de verde a gris verdadero. Esto eliminará las rayas verdes visuales cuando el framebuffer tenga valores 1 o 2, mostrándolos como gris claro y gris oscuro respectivamente.

Concepto de Hardware

Paleta de Colores en Game Boy

El framebuffer de la PPU contiene índices de color (0-3), no colores RGB directamente. El renderer debe convertir estos índices a colores RGB usando una paleta. La paleta estándar de Game Boy (greyscale) usa:

  • Color 0: Blanco (255, 255, 255) - el más claro
  • Color 1: Gris claro (170, 170, 170)
  • Color 2: Gris oscuro (85, 85, 85)
  • Color 3: Negro (0, 0, 0) - el más oscuro

Estos valores son estándar en emulación y proporcionan el contraste correcto para la visualización en escala de grises.

Paleta de Debug vs Paleta Real

La paleta de debug es una herramienta de diagnóstico que mapea índices a colores fijos para visualizar el contenido del framebuffer sin pasar por las paletas del hardware (BGP/OBP). Debe usar los mismos valores que la paleta estándar para representación correcta. Si la paleta de debug usa colores incorrectos (como verde en lugar de gris), cualquier valor en el framebuffer con ese índice se mostrará incorrectamente.

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

Implementación

Se identificaron 4 ubicaciones donde se definen paletas de debug con valores verdes para los índices 1 y 2, y se corrigieron cambiándolos a grises verdaderos según la constante PALETTE_GREYSCALE.

Ubicaciones Corregidas

  1. self.COLORS en __init__() (líneas 192-193):
    • Índice 1: (136, 192, 112) → (170, 170, 170)
    • Índice 2: (52, 104, 86) → (85, 85, 85)
  2. render_frame() con PPU C++ (líneas 494-499):
    • Índice 1: (136, 192, 112) → (170, 170, 170)
    • Índice 2: (52, 104, 86) → (85, 85, 85)
  3. render_frame() método Python (líneas 579-584):
    • Índice 1: (136, 192, 112) → (170, 170, 170)
    • Índice 2: (52, 104, 86) → (85, 85, 85)
  4. render_sprites() (líneas 955-960):
    • Índice 1: (136, 192, 112) → (170, 170, 170)
    • Índice 2: (52, 104, 86) → (85, 85, 85)

Valores Correctos

Todos los valores corregidos coinciden con la constante PALETTE_GREYSCALE definida en el módulo (líneas 53-58): 

PALETTE_GREYSCALE = [
    (255, 255, 255),  # Color 0: Blanco
    (170, 170, 170),  # Color 1: Gris claro
    (85, 85, 85),     # Color 2: Gris oscuro
    (0, 0, 0),        # Color 3: Negro
]

Consistencia

Todas las paletas de debug ahora usan los mismos valores para consistencia visual. Los comentarios también se actualizaron para reflejar que ahora son grises verdaderos, no verdes.

Archivos Afectados

  • src/gpu/renderer.py - Corregidas 4 ubicaciones de paletas (líneas 192-193, 494-499, 579-584, 955-960)
  • docs/bitacora/entries/2025-12-25__0303__correccion-paleta-debug-indices-1-2.html - Esta entrada (nuevo)
  • docs/bitacora/index.html - Actualizado con entrada 0303
  • INFORME_FASE_2.md - Actualizado con Step 0303

Tests y Verificación

La corrección es puramente visual y no requiere tests unitarios. Sin embargo, se recomienda:

  • Verificación visual: Ejecutar el emulador durante 5-10 minutos para verificar que las rayas verdes no aparecen
  • Inspección de código: Verificar que todas las paletas usan valores consistentes

Comando de verificación sugerido: 

python main.py roms/pkmn.gb

Validación: Confirmación visual de que:

  • Los píxeles con índice 0 se muestran en blanco
  • Los píxeles con índice 1 se muestran en gris claro (no verde)
  • Los píxeles con índice 2 se muestran en gris oscuro (no verde)
  • No hay rayas verdes después de varios minutos

Fuentes Consultadas

  • Pan Docs: "Background Palette (BGP)", "Object Palette (OBP)", "Palette"
  • Step 0302: Identificación del problema de paleta verde para índices 1 y 2

Integridad Educativa

Lo que Entiendo Ahora

  • Paleta de debug: Debe usar valores consistentes con la paleta estándar (greyscale) para representación correcta. Los colores verdes son incorrectos y causan confusión visual.
  • Mapeo de índices: El framebuffer contiene índices (0-3), no colores RGB. El renderer mapea estos índices a colores RGB usando una paleta. Si la paleta es incorrecta, la visualización será incorrecta.
  • Consistencia: Todas las paletas de debug deben usar los mismos valores para consistencia visual entre fondo, sprites y diferentes métodos de renderizado.
  • Corrección de bugs visuales: Los bugs visuales pueden deberse a problemas en la paleta de mapeo, no necesariamente en el framebuffer o en la lógica de renderizado.

Lo que Falta Confirmar

  • Efectividad de la corrección: Si esta corrección elimina completamente las rayas verdes después de 5-10 minutos de ejecución (verificación visual pendiente).
  • Causa raíz del framebuffer: Por qué el framebuffer comienza a tener valores 1 o 2 después de ~5 minutos (esto no se corrigió, solo la visualización).

Hipótesis y Suposiciones

Hipótesis principal: Las rayas verdes desaparecerán después de esta corrección porque ahora los valores 1 y 2 del framebuffer se mostrarán como grises verdaderos, no verdes. Esta hipótesis se basa en:

  • Los monitores del Step 0302 mostraron que la paleta nunca cambia durante la ejecución
  • El problema visual (rayas verdes) aparecía cuando el framebuffer tenía valores 1 o 2
  • La paleta de debug usaba colores verdes para índices 1 y 2

Suposiciones:

  • El framebuffer seguirá teniendo valores 1 o 2 después de ~5 minutos (esto no se corrigió)
  • Los valores 1 y 2 son correctos y solo necesitaban visualizarse como grises, no verdes

Próximos Pasos

  • [ ] Verificación visual extendida: Ejecutar el emulador durante 10+ minutos para verificar que las rayas verdes no aparecen
  • [ ] Si las rayas desaparecen: Continuar con otras funcionalidades del emulador
  • [ ] Si persisten problemas: Investigar por qué el framebuffer cambia de valores (Step 0304/0305)