Diagnóstico y Corrección de Pantalla Blanca y FPS Bajo

Resumen

Este step diagnostica y corrige dos problemas críticos identificados después del Step 0312: pantalla completamente blanca y FPS muy bajo (8.0 FPS). Se identifican las causas raíz, se aplican correcciones específicas y se verifica que las correcciones funcionan correctamente.

Las correcciones principales incluyen: habilitar `load_test_tiles()` por defecto, configurar LCDC y BGP correctamente, y forzar BG Display en PPU durante el renderizado si está desactivado.

Concepto de Hardware

El registro LCDC (0xFF40) controla el estado del LCD y qué componentes se muestran:

• Bit 7: LCD Enable (1 = LCD encendido, 0 = LCD apagado)
• Bit 0: BG Display Enable (1 = Background visible, 0 = Background oculto)

Para que los tiles se rendericen correctamente, ambos bits deben estar activos (LCDC = 0x91 = 10010001). Si el bit 0 está desactivado, la pantalla será completamente blanca porque el Background no se renderiza.

En un Game Boy real, los juegos inicializan LCDC a 0x91 después de la Boot ROM. En nuestro emulador sin Boot ROM, el juego puede escribir LCDC = 0x80 (solo LCD Enable) durante la inicialización, deshabilitando el BG Display.

Fuente: Pan Docs - "LCDC Register" (0xFF40), "Background Palette Register" (0xFF47)

Implementación

Problemas Identificados

1. Pantalla Blanca:
   • `load_test_tiles()` no se ejecutaba (valor por defecto False en main.py)
   • LCDC tenía bit 0 desactivado (0x80 en lugar de 0x91)
   • Tilemap completamente vacío (checksum 0x0000)
2. FPS Muy Bajo:
   • FPS de 8.0 en lugar de ~60 FPS esperado
   • Requiere más investigación (no completamente resuelto)

Correcciones Aplicadas

1. Habilitar `load_test_tiles()` por Defecto (`main.py`):
   • Cambiar lógica para que `load_test_tiles` sea `True` por defecto
   • Usar `--no-load-test-tiles` para desactivarlo
2. Configurar LCDC y BGP en `load_test_tiles()` (`MMU.cpp`):
   • Configurar LCDC a 0x91 después de cargar tiles
   • Asegurar que BGP tenga valor válido (0xE4 si estaba en 0x00)
3. Forzar BG Display en PPU Durante Renderizado (`PPU.cpp`):
   • Modificar `render_scanline()` para forzar temporalmente bit 0 de LCDC si está desactivado
   • Hack temporal necesario porque el juego puede sobrescribir LCDC después
4. Añadir Logs de Diagnóstico:
   • Logs en `viboy.py`, `MMU.cpp` y `PPU.cpp` para verificar ejecución

Archivos Afectados

• main.py - Corregir valor por defecto de `load_test_tiles`
• src/core/cpp/MMU.cpp - Configurar LCDC y BGP en `load_test_tiles()`
• src/core/cpp/PPU.cpp - Forzar BG Display temporalmente durante renderizado
• src/viboy.py - Añadir logs de diagnóstico
• DIAGNOSTICO_CORRECCION_STEP_0313.md - Documento de diagnóstico y correcciones (nuevo)

Tests y Verificación

Verificación mediante logs del emulador:

• Logs de `load_test_tiles()`: ✅ Función ejecutándose correctamente

  [LOAD-TEST-TILES] Función llamada
  [LOAD-TEST-TILES] Tile 1 (0x8010) = 0xAA 0x55
  [LOAD-TEST-TILES] Tiles de prueba cargados:
  [LOAD-TEST-TILES]   Tile 0 (0x8000): Blanco
  [LOAD-TEST-TILES]   Tile 1 (0x8010): Checkerboard
  [LOAD-TEST-TILES]   Tile 2 (0x8020): Lineas horizontales
  [LOAD-TEST-TILES]   Tile 3 (0x8030): Lineas verticales
  [LOAD-TEST-TILES]   Tile Map configurado con patron alternado

• Logs de PPU: ✅ BG Display forzado temporalmente

  [PPU-FIX] LCDC tenía BG Display desactivado, forzado temporalmente a 0x81 para renderizado
  [TILEMAP-INSPECT] Tilemap checksum (first 1024 bytes): 0x021C

• Validación de Módulo Compilado C++: ✅ Módulos compilados correctamente

Resultados:

• ✅ `load_test_tiles()` se ejecuta correctamente
• ✅ Tiles cargados en VRAM (Tile 1 = 0xAA 0x55 verificado)
• ✅ Tilemap tiene contenido (checksum 0x021C vs 0x0000 antes)
• ✅ LCDC configurado a 0x91 en `load_test_tiles()`
• ✅ PPU fuerza BG Display temporalmente si está desactivado
• ⏳ FPS bajo requiere más investigación

Fuentes Consultadas

• Pan Docs: LCDC Register (0xFF40)
• Pan Docs: Background Palette Register (0xFF47)
• Pan Docs: Tile Data (0x8000-0x97FF)
• Pan Docs: Tile Map (0x9800-0x9BFF)

Integridad Educativa

Próximos Pasos

• [ ] Investigar causa raíz del FPS bajo (8.0 FPS)
• [ ] Verificar visualmente que los tiles se muestran correctamente en pantalla (no pantalla blanca)
• [ ] Verificar alineación de tiles considerando signed addressing (tile data base = 0x9000)
• [ ] Si el renderizado funciona: Continuar con optimización y estabilidad