Investigación de Conversión de Índices a RGB y Orden de Píxeles

Resumen

Investigación exhaustiva del orden de píxeles en el framebuffer, la conversión de índices a RGB y el dibujo de píxeles en Pygame. Se implementaron 4 bloques de logs de diagnóstico para verificar el formato del framebuffer (orden de píxeles), la aplicación de la paleta (conversión de índices a RGB), el dibujo de píxeles en la superficie de Pygame y el escalado de la imagen. El objetivo es identificar por qué el contenido visual muestra rayas verticales en lugar del checkerboard esperado, investigando posibles problemas en el orden de píxeles, la conversión de índices a RGB o el dibujo en Pygame.

Concepto de Hardware

Formato del Framebuffer

El framebuffer está en formato 1D: [y * 160 + x] donde:

• y es la línea (0-143)
• x es la columna (0-159)
• idx = y * 160 + x da el índice en el array 1D
• Para convertir de índice a coordenadas: y = idx // 160, x = idx % 160

Este formato permite almacenar una imagen de 160×144 píxeles en un array lineal de 23040 elementos (160×144 = 23040). Cada elemento contiene un índice de color (0-3).

Paleta de Colores

La paleta debug mapea índices 0-3 a colores RGB:

• Índice 0: (255, 255, 255) - Blanco
• Índice 1: (170, 170, 170) - Gris Claro
• Índice 2: (85, 85, 85) - Gris Oscuro
• Índice 3: (8, 24, 32) - Negro

La conversión de índices a RGB debe ser directa: rgb_color = palette[color_index]. Esta paleta permite visualizar el contenido del framebuffer con alto contraste, independientemente de la paleta real del hardware (BGP/OBP).

Renderizado en Pygame

Pygame ofrece varias formas de dibujar píxeles:

• NumPy: Usa surfarray.blit_array() con formato (width, height, channels). El array numpy debe estar en formato (160, 144, 3) para RGB.
• PixelArray: Usa px_array[x, y] = color para dibujar píxeles individuales. El orden es (x, y), no (y, x).
• Escalado: Usa pygame.transform.scale() para escalar la superficie a la resolución de pantalla. El escalado puede causar interpolación que cambie ligeramente los colores.

Fuente: Pan Docs - "LCD Timing", "Frame Rate", "Tile Data", "LCD Control Register"

Implementación

Se implementaron 4 bloques de logs de diagnóstico en src/gpu/renderer.py para investigar el orden de píxeles, la conversión de índices a RGB, el dibujo de píxeles y el escalado.

1. Verificación del Orden de Píxeles en el Framebuffer

Se agregaron logs para verificar que el orden de los píxeles en el framebuffer es correcto (formato [y * 160 + x]).

• Verificación de línea horizontal: Verifica píxeles en una línea horizontal (y=0, x=0 a x=10) para confirmar que el orden horizontal es correcto
• Verificación de columna vertical: Verifica píxeles en una columna vertical (x=0, y=0 a y=10) para confirmar que el orden vertical es correcto
• Verificación de patrón checkerboard: Verifica píxeles adyacentes para confirmar que el patrón checkerboard esperado se refleja correctamente en el framebuffer
• Tag: [Renderer-Pixel-Order]

2. Verificación Detallada de Conversión de Índices a RGB

Se agregaron logs para verificar que la conversión de índices a RGB es correcta y que la paleta se aplica correctamente.

• Verificación de paleta: Verifica que la paleta tiene los valores correctos (0=Blanco, 1=Gris Claro, 2=Gris Oscuro, 3=Negro)
• Verificación de píxeles específicos: Verifica algunos píxeles específicos (esquinas, centro, píxeles aleatorios) para confirmar que la conversión es correcta
• Validación de índices: Verifica que los índices están en rango válido (0-3) y que el RGB resultante es válido
• Tag: [Renderer-RGB-Conversion]

3. Verificación del Dibujo de Píxeles en Pygame

Se agregaron logs para verificar que los píxeles se dibujan correctamente en la superficie de Pygame después de aplicar la paleta.

• Lectura de colores de la superficie: Lee el color de la superficie después de dibujar los píxeles usando surface.get_at((x, y))
• Comparación con valores esperados: Compara el color leído de la superficie con el color esperado según la paleta
• Verificación de correspondencia: Verifica que el color en la superficie coincide con el color esperado (tolerancia de ±5 para interpolación)
• Tag: [Renderer-Pixel-Draw]

4. Verificación del Escalado y Visualización Final

Se agregaron logs para verificar que el escalado no causa artefactos significativos y que el contenido escalado coincide con el original.

• Comparación antes/después del escalado: Compara el color de píxeles antes del escalado (superficie original 160×144) y después del escalado (superficie escalada)
• Verificación de interpolación: Verifica que los colores escalados son similares a los originales (tolerancia de ±20 para interpolación de escalado)
• Tag: [Renderer-Scale-Visualization]

Archivos Afectados

• src/gpu/renderer.py - Agregados 4 bloques de logs de diagnóstico para investigar el orden de píxeles, conversión RGB, dibujo de píxeles y escalado

Tests y Verificación

Se implementaron logs de diagnóstico que se activan en los primeros 10 frames para evitar saturación del contexto. Los logs se generan durante la ejecución normal del emulador.

Comandos de Prueba

Para ejecutar pruebas con las 5 ROMs y generar logs:

timeout 150 python3 main.py roms/pkmn.gb 2>&1 | tee logs/test_pkmn_step0341.log
timeout 150 python3 main.py roms/tetris.gb 2>&1 | tee logs/test_tetris_step0341.log
timeout 150 python3 main.py roms/mario.gbc 2>&1 | tee logs/test_mario_step0341.log
timeout 150 python3 main.py roms/pkmn-amarillo.gb 2>&1 | tee logs/test_pkmn_amarillo_step0341.log
timeout 150 python3 main.py roms/Oro.gbc 2>&1 | tee logs/test_oro_step0341.log

Análisis de Logs

Para analizar los logs sin saturar el contexto:

# Verificar orden de píxeles
grep "\[Renderer-Pixel-Order\]" logs/test_*_step0341.log | head -n 50

# Verificar conversión de índices a RGB
grep "\[Renderer-RGB-Conversion\]" logs/test_*_step0341.log | head -n 50

# Verificar dibujo de píxeles
grep "\[Renderer-Pixel-Draw\]" logs/test_*_step0341.log | head -n 30

# Verificar escalado
grep "\[Renderer-Scale-Visualization\]" logs/test_*_step0341.log | head -n 30

Validación

Los logs permiten verificar:

• Que el orden de píxeles en el framebuffer es correcto (formato [y * 160 + x])
• Que la conversión de índices a RGB es correcta y la paleta se aplica correctamente
• Que los píxeles se dibujan correctamente en la superficie de Pygame
• Que el escalado no causa artefactos significativos

Fuentes Consultadas

• Pan Docs: "LCD Timing", "Frame Rate", "Tile Data", "LCD Control Register"
• Documentación de Pygame: pygame.Surface, pygame.PixelArray, pygame.transform.scale()

Integridad Educativa

Próximos Pasos

• [ ] Ejecutar pruebas completas con las 5 ROMs (2.5 minutos cada una)
• [ ] Analizar los logs generados para identificar la causa del problema visual
• [ ] Si se identifica la causa, implementar la corrección en el siguiente step
• [ ] Si el problema persiste, realizar análisis más profundo y solución alternativa