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

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

Resumen

Corrección de la paleta de debug en el renderer de Python que estaba causando que los píxeles con índice 0 (blanco) se mostraran como verde. El color del índice 0 se cambió de (224, 248, 208) (verde) a (255, 255, 255) (blanco verdadero) en los 3 lugares donde se define la paleta de debug.

Objetivo: Corregir el problema de las rayas verdes identificado en el Step 0299, donde el análisis del framebuffer confirmó que todos los píxeles tienen índice 0 (correcto), pero el renderer los mostraba en verde debido a una paleta de debug incorrecta.

Concepto de Hardware

Paleta de Colores en Game Boy

El framebuffer de la Game Boy contiene índices de color (0-3), no colores RGB directos. El renderer de Python debe convertir estos índices a colores RGB para mostrarlos en pantalla.

La paleta de debug es una herramienta de diagnóstico que mapea índices a colores fijos para visualizar el contenido del framebuffer sin depender de la paleta BGP del hardware. En hardware real, la paleta BGP (Background Palette, registro 0xFF47) mapea los índices a colores según la configuración del juego.

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

Paleta Estándar de Game Boy (Greyscale)

La paleta estándar de Game Boy en modo monocromo (DMG) mapea los índices a tonos de gris:

Color 0 (índice 0): Blanco (RGB: 255, 255, 255)
Color 1 (índice 1): Gris claro (RGB: 170, 170, 170)
Color 2 (índice 2): Gris oscuro (RGB: 85, 85, 85)
Color 3 (índice 3): Negro (RGB: 0, 0, 0)

El problema identificado en el Step 0299 era que la paleta de debug mapeaba incorrectamente el índice 0 a un color verde (224, 248, 208) en lugar de blanco verdadero. Esto causaba que todos los píxeles con índice 0 (que es el valor correcto para píxeles vacíos) se mostraran en verde, generando el efecto de "rayas verdes" en la pantalla.

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

Implementación

Se corrigió la paleta de debug en 3 lugares del archivo src/gpu/renderer.py:

Línea 470: Paleta de debug en render_frame() cuando usa PPU C++
Línea 538: Paleta de debug en render_frame() método Python
Línea 897: Paleta de debug en render_sprites()

Cambio Realizado

Se cambió el color del índice 0 de verde a blanco verdadero:

# ANTES (incorrecto):
debug_palette_map = {
    0: (224, 248, 208),  # 00: White/Greenish (Color 0)
    ...
}

# DESPUÉS (correcto):
debug_palette_map = {
    0: (255, 255, 255),  # 00: White (Color 0) - Corregido Step 0300
    ...
}

Componentes Modificados

src/gpu/renderer.py: Corregida paleta de debug en 3 funciones (render_frame con PPU C++, render_frame método Python, render_sprites)

Decisiones de Diseño

Se mantuvo la paleta de debug para los otros índices (1, 2, 3) sin cambios, ya que solo el índice 0 estaba incorrecto. La paleta de debug es una herramienta temporal para diagnóstico, por lo que no afecta la implementación final que usará la paleta BGP real del hardware.

Archivos Afectados

src/gpu/renderer.py - Corregida paleta de debug en 3 lugares (líneas 470, 538, 897)

Tests y Verificación

La corrección se validó mediante:

Análisis del Step 0299: El análisis del framebuffer confirmó que todos los píxeles tienen índice 0 (correcto), pero el renderer los mostraba en verde
Corrección directa: Cambio del color del índice 0 de verde a blanco en la paleta de debug
Verificación visual esperada: Al ejecutar el emulador, los píxeles vacíos (índice 0) ahora deberían mostrarse en blanco, no verde

Nota: Esta es una corrección simple de un valor RGB en el renderer de Python. No requiere recompilación de C++ ni tests unitarios adicionales, ya que el cambio es puramente visual y corrige un mapeo incorrecto de colores.

Fuentes Consultadas

Pan Docs: Background Palette (BGP)
Pan Docs: LCD Display
Análisis del Step 0299: Investigación de Rayas Verdes y Diagnóstico Visual

Integridad Educativa

Lo que Entiendo Ahora

Framebuffer contiene índices, no colores: El framebuffer de la PPU contiene índices de color (0-3), no valores RGB directos. El renderer debe convertir estos índices a colores RGB usando una paleta.
Paleta de debug vs paleta BGP: La paleta de debug es una herramienta temporal para diagnóstico que mapea índices a colores fijos. En producción, debería usarse la paleta BGP real del hardware (registro 0xFF47).
Índice 0 = Blanco: En la paleta estándar de Game Boy, el índice 0 corresponde a blanco (RGB: 255, 255, 255), no a verde.

Lo que Falta Confirmar

Verificación visual: Ejecutar el emulador con Pokémon Red para confirmar que las rayas verdes han desaparecido y que los píxeles vacíos se muestran en blanco.
Otros problemas visuales: Si aún hay problemas visuales después de esta corrección, investigar si hay otros problemas en el renderer o la PPU.

Hipótesis y Suposiciones

Suposición: La corrección de la paleta de debug debería resolver el problema de las rayas verdes, ya que el análisis del Step 0299 confirmó que el framebuffer contiene solo índices 0 (correcto) y el problema estaba en el mapeo de colores del renderer.

Próximos Pasos

[ ] Ejecutar el emulador con Pokémon Red para verificar visualmente que las rayas verdes han desaparecido
[ ] Si la pantalla se ve blanca/gris: Correcto - significa que la corrección funcionó
[ ] Si aún hay problemas visuales: Investigar si hay otros problemas en el renderer o la PPU
[ ] Si los tiles se cargan: Verificar que se rendericen correctamente con la nueva paleta