Step 0396: Fix BGP Consistente y Renderizado Respetando Paleta del Juego

Resumen Ejecutivo

El Step 0395 identificó dos problemas críticos: BGP inconsistente (render_bg() forzaba 0xE4 mientras otras funciones leían desde MMU) y Frame 676 blanco (framebuffer completamente blanco aunque VRAM tenía 14.2% TileData). Este step corrige la inconsistencia eliminando el hardcode de BGP=0xE4 y haciendo que render_bg() lea BGP desde MMU, respetando la paleta que el juego configura.

Resultados clave:

• Tetris DX: BGP cambia de 0xE4 → 0x00 en Frame 577 (intencional para fade out), luego 0x00 → 0xE4 en Frame 675.
• Zelda DX: BGP=0x00 desde Frame 1 (pantalla blanca intencional durante carga).
• Frame 676 (Tetris): BGP=0xE4, vram_has_tiles=0, tilemap vacío (0x00), explicando framebuffer blanco.
• Frame 676 (Zelda): BGP=0x00, vram_is_empty_=1, tilemap con 0x7F (tile vacío), explicando framebuffer blanco.

Concepto de Hardware

Registro BGP (Background Palette - 0xFF47)

Según Pan Docs, el registro BGP (0xFF47) controla cómo se mapean los índices de color del Background (0-3) a los colores finales de la pantalla en Game Boy clásico (DMG). Cada par de bits en BGP representa el color final para un índice:

BGP = 0xE4 = 11 10 01 00 (binario)
  Índice 3 → Color 3 (negro)
  Índice 2 → Color 2 (gris oscuro)
  Índice 1 → Color 1 (gris claro)
  Índice 0 → Color 0 (blanco)

Valores comunes:

• 0xE4: Mapeo identidad (estándar, usado por la mayoría de juegos)
• 0xFC: Post-BIOS (valor inicial después del bootrom)
• 0x00: Todo mapea a blanco (usado para fade out o transiciones)

Problema identificado: El código original en render_bg() (línea 2208) forzaba BGP=0xE4 hardcodeado, ignorando el valor que el juego escribía en la MMU. Esto causaba inconsistencia con otras funciones (líneas 3803, 3915, 4459) que sí leían BGP desde MMU.

Solución: Leer BGP desde MMU consistentemente en todas las funciones de renderizado, respetando el valor que el juego configura.

Problema Identificado

1. BGP Inconsistente

Código original:

// render_bg() línea 2208 (ANTES)
uint8_t bgp = 0xE4;  // Hardcodeado

// Otras funciones (líneas 3803, 3915, 4459)
uint8_t bgp = mmu_->read(IO_BGP);  // Leído desde MMU

Consecuencia: Si el juego escribía BGP=0x00 a la MMU (para fade out), render_bg() ignoraba el cambio y seguía usando 0xE4, mientras otras funciones usaban 0x00, causando inconsistencia visual.

2. Frame 676 Blanco (Tetris DX)

El Step 0395 detectó que Frame 676 tenía framebuffer completamente blanco (0=23040) aunque VRAM tenía 14.2% TileData. El diagnóstico del Step 0396 reveló:

• BGP: 0xE4 (correcto)
• vram_has_tiles: 0 (VRAM todavía considerado vacío por el sistema de detección)
• Tilemap: Primeros 10 tiles = 0x00 (tilemap vacío)
• Tiledata: Primeros 16 bytes = 0x00 (tile 0 vacío)

Conclusión: El framebuffer blanco en Frame 676 es correcto porque el tilemap apunta a tiles vacíos (0x00), no porque BGP esté mal.

3. Frame 676 Blanco (Zelda DX)

Diagnóstico del Step 0396:

• BGP: 0x00 (todo mapea a blanco - intencional del juego)
• vram_is_empty_: 1 (VRAM todavía vacío)
• Tilemap: Primeros 10 tiles = 0x7F (tile vacío en modo signed addressing)
• Tiledata: Primeros 16 bytes = 0x00 (tile 0 vacío)

Conclusión: El framebuffer blanco en Frame 676 (Zelda) es intencional: el juego usa BGP=0x00 para pantalla blanca durante carga.

Implementación

1. Lectura Consistente de BGP desde MMU

Archivo: src/core/cpp/PPU.cpp (línea 2203-2229)

// --- Step 0396: BGP CONSISTENTE DESDE MMU ---
// Leer BGP desde MMU para respetar la paleta que el juego configura.
// Anteriormente forzábamos 0xE4, pero esto causaba inconsistencia cuando
// el juego escribía otros valores (ej: 0x00 para fade out).
static uint8_t last_bgp = 0xFF;
uint8_t bgp = mmu_->read(IO_BGP);

// Log limitado de cambios de BGP (solo en LY=0, máx 10 cambios)
if (bgp != last_bgp && ly_ == 0) {
    static int bgp_change_log_count = 0;
    if (bgp_change_log_count < 10) {
        bgp_change_log_count++;
        printf("[PPU-BGP-CHANGE] Frame %llu | BGP: 0x%02X -> 0x%02X\n", 
               frame_counter_ + 1, last_bgp, bgp);
    }
    last_bgp = bgp;
}

// Advertencia limitada si BGP=0x00 (todo mapea a blanco - puede ser intencional)
if (bgp == 0x00 && ly_ == 0) {
    static int bgp_zero_warning_count = 0;
    if (bgp_zero_warning_count < 5) {
        bgp_zero_warning_count++;
        printf("[PPU-BGP-WARNING] Frame %llu | BGP=0x00 (todo mapea a blanco) - "
               "¿Intencional del juego?\n", frame_counter_ + 1);
    }
}

2. Diagnóstico Frame 676 Específico

Archivo: src/core/cpp/PPU.cpp (línea 2231-2257)

// --- Step 0396: Diagnóstico Frame 676 específico ---
// Frame 676 mostró framebuffer blanco aunque VRAM tenía 14.2% TileData
if (frame_counter_ + 1 == 676 && ly_ == 0) {
    printf("[FRAME676-DIAG] === DIAGNÓSTICO FRAME 676 ===\n");
    printf("[FRAME676-DIAG] BGP actual: 0x%02X\n", bgp);
    printf("[FRAME676-DIAG] vram_is_empty_: %d\n", vram_is_empty_ ? 1 : 0);
    printf("[FRAME676-DIAG] vram_has_tiles: %d\n", vram_has_tiles ? 1 : 0);
    printf("[FRAME676-DIAG] LCDC: 0x%02X (BG Enable: %d)\n", 
           lcdc, (lcdc & 0x01) ? 1 : 0);
    printf("[FRAME676-DIAG] Tilemap base: 0x%04X\n", tile_map_base);
    printf("[FRAME676-DIAG] Tiledata base: 0x%04X\n", tile_data_base);
    
    // Verificar primeros 10 tile IDs del tilemap
    printf("[FRAME676-DIAG] Primeros 10 tile IDs: ");
    for (int i = 0; i < 10; i++) {
        uint8_t tile_id = mmu_->read(tile_map_base + i);
        printf("0x%02X ", tile_id);
    }
    printf("\n");
    
    // Verificar primeros 16 bytes del primer tile
    printf("[FRAME676-DIAG] Primeros 16 bytes del tile 0: ");
    for (int i = 0; i < 16; i++) {
        uint8_t tile_byte = mmu_->read(tile_data_base + i);
        printf("0x%02X ", tile_byte);
    }
    printf("\n[FRAME676-DIAG] === FIN DIAGNÓSTICO ===\n");
}

Tests y Verificación

Comandos Ejecutados

cd /media/fabini/8CD1-4C30/ViboyColor
python3 setup.py build_ext --inplace
timeout 30s python3 main.py roms/tetris_dx.gbc > logs/step0396_tetris_dx.log 2>&1
timeout 30s python3 main.py roms/Oro.gbc > logs/step0396_zelda_dx.log 2>&1

Resultados: Cambios de BGP

Tetris DX:

[PPU-BGP-CHANGE] Frame 1 | BGP: 0xFF -> 0xE4
[PPU-BGP-CHANGE] Frame 577 | BGP: 0xE4 -> 0x00
[PPU-BGP-WARNING] Frame 577 | BGP=0x00 (todo mapea a blanco) - ¿Intencional del juego?
[PPU-BGP-WARNING] Frame 578 | BGP=0x00 (todo mapea a blanco) - ¿Intencional del juego?
[PPU-BGP-WARNING] Frame 579 | BGP=0x00 (todo mapea a blanco) - ¿Intencional del juego?
[PPU-BGP-WARNING] Frame 580 | BGP=0x00 (todo mapea a blanco) - ¿Intencional del juego?
[PPU-BGP-WARNING] Frame 581 | BGP=0x00 (todo mapea a blanco) - ¿Intencional del juego?
[PPU-BGP-CHANGE] Frame 675 | BGP: 0x00 -> 0xE4
[PPU-BGP-CHANGE] Frame 732 | BGP: 0xE4 -> 0x00

Zelda DX:

[PPU-BGP-CHANGE] Frame 1 | BGP: 0xFF -> 0x00
[PPU-BGP-WARNING] Frame 1 | BGP=0x00 (todo mapea a blanco) - ¿Intencional del juego?
[PPU-BGP-WARNING] Frame 2 | BGP=0x00 (todo mapea a blanco) - ¿Intencional del juego?
[PPU-BGP-WARNING] Frame 3 | BGP=0x00 (todo mapea a blanco) - ¿Intencional del juego?
[PPU-BGP-WARNING] Frame 4 | BGP=0x00 (todo mapea a blanco) - ¿Intencional del juego?

Resultados: Diagnóstico Frame 676

Tetris DX:

[FRAME676-DIAG] === DIAGNÓSTICO FRAME 676 ===
[FRAME676-DIAG] BGP actual: 0xE4
[FRAME676-DIAG] vram_is_empty_: 0
[FRAME676-DIAG] vram_has_tiles: 0
[FRAME676-DIAG] LCDC: 0x91 (BG Enable: 1)
[FRAME676-DIAG] Tilemap base: 0x9800
[FRAME676-DIAG] Tiledata base: 0x8000
[FRAME676-DIAG] Primeros 10 tile IDs: 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 
[FRAME676-DIAG] Primeros 16 bytes del tile 0: 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 
[FRAME676-DIAG] === FIN DIAGNÓSTICO ===

Zelda DX:

[FRAME676-DIAG] === DIAGNÓSTICO FRAME 676 ===
[FRAME676-DIAG] BGP actual: 0x00
[FRAME676-DIAG] vram_is_empty_: 1
[FRAME676-DIAG] vram_has_tiles: 0
[FRAME676-DIAG] LCDC: 0xE3 (BG Enable: 1)
[FRAME676-DIAG] Tilemap base: 0x9800
[FRAME676-DIAG] Tiledata base: 0x9000
[FRAME676-DIAG] Primeros 10 tile IDs: 0x7F 0x7F 0x7F 0x7F 0x7F 0x7F 0x7F 0x7F 0x7F 0x7F 
[FRAME676-DIAG] Primeros 16 bytes del tile 0: 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 
[FRAME676-DIAG] === FIN DIAGNÓSTICO ===

Validación

• ✅ Compilación: Exitosa sin errores de linter
• ✅ BGP Consistente: render_bg() lee BGP desde MMU correctamente
• ✅ Cambios de BGP: Detectados y logueados (Tetris: 0xE4→0x00→0xE4, Zelda: 0x00 constante)
• ✅ Frame 676 (Tetris): Framebuffer blanco explicado por tilemap vacío (0x00), no por BGP
• ✅ Frame 676 (Zelda): Framebuffer blanco explicado por BGP=0x00 intencional
• ✅ Validación Nativa: Módulo C++ compilado y ejecutado correctamente

Hallazgos Clave

1. BGP Dinámico en Juegos Reales

Los juegos cambian BGP dinámicamente para efectos visuales:

• Tetris DX: Usa BGP=0x00 durante ~98 frames (577-675) para fade out entre pantallas
• Zelda DX: Usa BGP=0x00 al inicio para pantalla blanca durante carga

Implicación: El hardcode de BGP=0xE4 era incorrecto y causaba inconsistencia visual.

2. Frame 676 No Era un Bug de BGP

El framebuffer blanco en Frame 676 (Tetris) no era causado por BGP inconsistente, sino por:

• Tilemap vacío: Primeros 10 tile IDs = 0x00
• Tile 0 vacío: Primeros 16 bytes = 0x00
• vram_has_tiles=0: Sistema de detección todavía no detectaba tiles cargados

Conclusión: El renderizado es correcto. El problema está en el timing de carga de VRAM o en la detección de tiles cargados.

3. BGP=0x00 es Legítimo

Según Pan Docs, BGP=0x00 es un valor válido que mapea todos los índices de color a blanco. Algunos juegos lo usan intencionalmente para:

• Fade out (Tetris DX)
• Pantalla blanca durante carga (Zelda DX)
• Transiciones entre escenas

Implicación: El emulador debe respetar BGP=0x00 sin forzar un mínimo.

Tabla Resumen: Cambios de BGP Detectados

Próximos Pasos

Con BGP ahora consistente, los próximos steps deben enfocarse en:

1. Mejorar detección de VRAM cargado: vram_has_tiles=0 en Frame 676 aunque VRAM tiene 14.2% TileData
2. Verificar timing de carga de VRAM: ¿Por qué el tilemap apunta a tiles vacíos en Frame 676?
3. Implementar verificación de tiles cargados: Detectar cuando el juego carga tiles no-vacíos
4. Optimizar renderizado: Ahora que BGP es correcto, verificar si hay otros problemas de paleta

Archivos Modificados

• src/core/cpp/PPU.cpp - Lectura consistente de BGP desde MMU, diagnóstico Frame 676
• logs/step0396_tetris_dx.log - Log de ejecución Tetris DX (30s)
• logs/step0396_zelda_dx.log - Log de ejecución Zelda DX (30s)
• build_log_step0396.txt - Log de compilación

Referencias

• Pan Docs - Palettes (BGP, OBP0, OBP1)
• Pan Docs - LCDC Register
• Pan Docs - Rendering