Step 0406: Pipeline CGB RGB y Paletas por Tile

💡 Concepto de Hardware

El Game Boy Color introduce un sistema de paletas sofisticado que permite hasta 32 colores simultáneos en pantalla:

• 8 paletas BG × 4 colores = 32 colores para Background
• BG Map Attributes (VRAM Bank 1) definen qué paleta usar para cada tile
• Bits 0-2 del attribute byte = palette number (0-7)

BG Map Attributes (VRAM Bank 1)

Bit 0-2: Palette number (0-7)
Bit 3:   Tile VRAM bank (0=Bank 0, 1=Bank 1)
Bit 5:   X-Flip
Bit 6:   Y-Flip
Bit 7:   BG-to-OAM Priority

Formato de Paletas CGB (BGR555)

Cada color usa 2 bytes (BGR555):
  GGGRRRRR XBBBBBGG (Little Endian, X = unused)

Conversión BGR555 → RGB888:
  R5 = (color >> 0) & 0x1F
  G5 = (color >> 5) & 0x1F
  B5 = (color >> 10) & 0x1F
  R8 = (R5 * 255) / 31  # Scale to 0-255
  G8 = (G5 * 255) / 31
  B8 = (B5 * 255) / 31

Fuente: Pan Docs - CGB Registers, BG Map Attributes, Color Palettes

⚙️ Implementación

Tarea 1: Aplicar BG Attributes (Paleta por Tile)

Modificada PPU::convert_framebuffer_to_rgb() para leer attributes de VRAM bank 1:

// Para cada píxel (x,y):
uint8_t world_x = (x + scx) & 0xFF;  // Aplicar scroll con wrap
uint8_t world_y = (y + scy) & 0xFF;
uint8_t tile_x = world_x / 8;
uint8_t tile_y = world_y / 8;

// Leer attribute de VRAM bank 1
uint16_t tilemap_offset = tile_y * 32 + tile_x;
uint8_t attributes = mmu_->read_vram_bank(1, tilemap_base + tilemap_offset);

// Extraer palette_id (bits 0-2)
uint8_t palette_id = attributes & 0x07;

// Usar paleta correcta para este tile
uint16_t bgr555 = cgb_palettes[palette_id][color_index];

Tarea 2: Ejecutar Conversión al Final de Frame

Añadida llamada a convert_framebuffer_to_rgb() en swap_framebuffers() para sincronización perfecta:

void PPU::swap_framebuffers() {
    std::swap(framebuffer_front_, framebuffer_back_);
    framebuffer_swap_pending_ = false;
    std::fill(framebuffer_back_.begin(), framebuffer_back_.end(), 0);
    
    // Step 0406: Convertir índices a RGB después del swap
    convert_framebuffer_to_rgb();
}

Tarea 3: Integrar Render RGB en Python

Modificado viboy.py para detectar modo CGB y usar buffer RGB:

hardware_mode = self._mmu.get_hardware_mode()

if hardware_mode == "CGB":
    rgb_view = self._ppu.get_framebuffer_rgb()
    self._renderer.render_frame(rgb_view=rgb_view)
else:
    # Modo DMG: usar índices + BGP
    self._renderer.render_frame(framebuffer_data=framebuffer_to_render)

Añadido soporte en Renderer.render_frame() para buffer RGB:

if rgb_view is not None:
    rgb_array = np.frombuffer(rgb_view, dtype=np.uint8)
    rgb_reshaped = rgb_array.reshape((GB_HEIGHT, GB_WIDTH, 3))
    rgb_transposed = np.transpose(rgb_reshaped, (1, 0, 2))
    pygame.surfarray.blit_array(self.screen, rgb_transposed)
    pygame.display.flip()

🧪 Tests y Verificación

Compilación

$ python3 setup.py build_ext --inplace
✅ Compilación exitosa
⚠️  Warnings de formato (no críticos)

Test: Tetris DX (CGB ROM)

$ timeout 30s python3 main.py roms/tetris_dx.gbc

Resultados:
✅ Modo CGB detectado correctamente
✅ BG attributes leyéndose de VRAM bank 1
✅ Pipeline RGB funcionando sin errores
✅ Logs de [CGB-BG-ATTR] muestran lectura de attributes

Evidencia:
[MMU] ROM CGB detectada (flag=0x80). Modo hardware: CGB
[MMU] Registros I/O inicializados para modo CGB
[CGB-BG-ATTR] LY:0 X:0 | TileMapAddr:0x9800 | TileID:0x00 | Attr:0x00
[Renderer-RGB-CGB] Frame renderizado correctamente desde RGB888

Estado de Otros Juegos

• Tetris DX: ✅ Funciona, progresa (GameplayState=YES)
• Zelda DX / Pokémon Red: ⚠️ Requieren Boot ROM para inicialización correcta

📄 Archivos Afectados

• src/core/cpp/PPU.cpp - Implementación de paletas por tile en convert_framebuffer_to_rgb()
• src/core/cpp/PPU.cpp - Llamada a conversión RGB en swap_framebuffers()
• src/viboy.py - Detección de modo CGB y uso de RGB buffer
• src/gpu/renderer.py - Soporte para rgb_view en render_frame()

📊 Conclusiones