Forzar Renderizado y Scroll (SCX/SCY)

Resumen

Se implementó un "hack educativo" para ignorar el Bit 0 de LCDC (BG Display) cuando el Bit 7 (LCD Enable) está activo, permitiendo que juegos CGB como Tetris DX que escriben LCDC=0x80 puedan mostrar gráficos. Además, se implementó el scroll (SCX/SCY) que permite desplazar la "cámara" sobre el tilemap de 256x256 píxeles. El renderizado se cambió de dibujar por tiles a dibujar píxel a píxel para soportar correctamente el scroll. Se crearon 5 tests para validar el scroll y el renderizado forzado, todos pasando correctamente.

Concepto de Hardware

El registro LCDC (0xFF40) tiene diferentes comportamientos según el modelo de Game Boy:

• Game Boy Clásica (DMG): El Bit 0 (BG Display) controla directamente si el fondo se dibuja o no. Si Bit 0=0, el fondo no se renderiza (pantalla blanca).
• Game Boy Color (CGB): El Bit 0 no apaga el fondo, sino que cambia la prioridad de sprites vs fondo. El fondo SIEMPRE se dibuja en CGB (a menos que haya Master Priority activo).

Tetris DX es un juego CGB/dual que detecta el hardware y puede escribir LCDC=0x80 (Bit 7=1, Bit 0=0) esperando el comportamiento CGB donde el fondo se dibuja de todas formas. Nuestro emulador actúa como DMG estricta y apagaría el fondo, resultando en pantalla blanca.

Los registros de Scroll permiten desplazar la "cámara" sobre el tilemap:

• SCX (0xFF43): Scroll X - desplazamiento horizontal (0-255)
• SCY (0xFF42): Scroll Y - desplazamiento vertical (0-255)

El tilemap es de 32x32 tiles = 256x256 píxeles. La pantalla muestra solo 160x144 píxeles (20x18 tiles). El scroll permite "mover la cámara" sobre el tilemap completo. La fórmula es:

map_pixel_x = (screen_pixel_x + SCX) % 256
map_pixel_y = (screen_pixel_y + SCY) % 256

El wrap-around (módulo 256) permite que el scroll sea continuo y cíclico.

Fuente: Pan Docs - LCD Control Register, Game Boy Color differences, Scroll Registers (SCX/SCY)

Implementación

Hack Educativo: Ignorar Bit 0 de LCDC

Se comentó la verificación del Bit 0 de LCDC en render_frame() y se añadió documentación explicando que es un hack temporal para compatibilidad con juegos CGB. El código original queda comentado para referencia futura. Ahora, si el Bit 7 (LCD Enable) está activo, el fondo se dibuja siempre, independientemente del Bit 0.

Implementación de Scroll (SCX/SCY)

Se cambió el renderizado de tile a tile a píxel a píxel para soportar correctamente el scroll:

• Se leen los registros SCX y SCY de la MMU
• Para cada píxel de pantalla (0-159, 0-143), se calcula la posición en el tilemap aplicando scroll
• Se calcula qué tile corresponde y qué píxel dentro del tile
• Se decodifica el píxel específico del tile (leyendo los bits correspondientes de los 2 bytes de la línea)
• Se dibuja el píxel en la posición de pantalla con la paleta aplicada

El cambio de renderizado por tiles a píxel a píxel es más lento en Python, pero permite implementar el scroll correctamente y es más flexible para futuras mejoras (como Window, Sprites, etc.).

Componentes creados/modificados

• src/gpu/renderer.py: Modificado render_frame() para ignorar Bit 0 y implementar scroll píxel a píxel
• tests/test_gpu_scroll.py: Nuevo archivo con 5 tests para validar scroll y renderizado forzado

Decisiones de diseño

El hack del Bit 0 está claramente documentado como temporal y educativo. En el futuro, cuando se implemente modo CGB completo, el Bit 0 deberá funcionar correctamente según la especificación CGB.

El renderizado píxel a píxel es más lento pero más correcto y flexible. En el futuro, se podría optimizar renderizando por tiles cuando el scroll es múltiplo de 8, pero por ahora la implementación píxel a píxel es más clara y fácil de mantener.

Archivos Afectados

• src/gpu/renderer.py - Modificado render_frame() para ignorar Bit 0 de LCDC (hack educativo) e implementar scroll (SCX/SCY) con renderizado píxel a píxel
• tests/test_gpu_scroll.py - Nuevo archivo con 5 tests para validar scroll horizontal, vertical, wrap-around, renderizado forzado con LCDC=0x80, y scroll cero

Tests y Verificación

Tests Unitarios - Scroll y Renderizado Forzado

Comando ejecutado: python3 -m pytest tests/test_gpu_scroll.py -v

Entorno: macOS (darwin 21.6.0), Python 3.9.6, pytest 8.4.2

Resultado: 5 passed in 11.81s

Qué valida:

• test_scroll_x: Verifica que SCX desplaza correctamente el fondo horizontalmente. Si SCX=4, el píxel 0 de pantalla debe mostrar el píxel 4 del tilemap. Valida que el scroll horizontal funciona correctamente.
• test_scroll_y: Verifica que SCY desplaza correctamente el fondo verticalmente. Si SCY=8, la línea 0 de pantalla debe mostrar la línea 8 del tilemap. Valida que el scroll vertical funciona correctamente.
• test_scroll_wrap_around: Verifica que el scroll hace wrap-around correctamente (módulo 256). Si SCX=200 y screen_x=100, map_x = (100 + 200) % 256 = 44. Valida que el wrap-around funciona correctamente.
• test_force_bg_render_lcdc_0x80: Verifica que con LCDC=0x80 (bit 7=1, bit 0=0) se dibuja el fondo gracias al hack educativo. Valida que el hack permite que juegos CGB muestren gráficos.
• test_scroll_zero: Verifica que con SCX=0 y SCY=0, el renderizado funciona normalmente sin scroll. Valida que el renderizado funciona correctamente sin desplazamiento.

Código del Test - test_force_bg_render_lcdc_0x80

@patch('src.gpu.renderer.pygame.draw.rect')
def test_force_bg_render_lcdc_0x80(self, mock_draw_rect: MagicMock) -> None:
    """
    Test: Verificar que con LCDC=0x80 (bit 7=1, bit 0=0) se dibuja el fondo.
    
    Este test valida el "hack educativo" que ignora el Bit 0 de LCDC para
    permitir que juegos CGB (como Tetris DX) que escriben LCDC=0x80 puedan
    mostrar gráficos.
    """
    mmu = MMU(None)
    renderer = Renderer(mmu, scale=1)
    renderer.screen = MagicMock()
    
    # Configurar LCDC = 0x80 (bit 7=1 LCD ON, bit 0=0 BG OFF en DMG)
    # Con el hack, debería dibujar el fondo de todas formas
    mmu.write_byte(IO_LCDC, 0x80)
    mmu.write_byte(IO_BGP, 0xE4)
    
    # Configurar tilemap básico
    mmu.write_byte(0x9800, 0x00)
    
    # Configurar tile en 0x8000 (tile ID 0)
    for line in range(8):
        mmu.write_byte(0x8000 + (line * 2), 0x00)
        mmu.write_byte(0x8000 + (line * 2) + 1, 0x00)
    
    # Renderizar frame
    renderer.render_frame()
    
    # Verificar que se llamó a draw_rect (indicando que se dibujaron píxeles)
    assert mock_draw_rect.called, \
        "Con LCDC=0x80 (hack educativo), debe dibujar píxeles en lugar de retornar temprano"
    assert mock_draw_rect.call_count == 160 * 144, \
        f"Debe dibujar 160*144 píxeles, pero se llamó {mock_draw_rect.call_count} veces"
    
    renderer.quit()

Explicación académica: Este test demuestra que el hack educativo funciona correctamente. Con LCDC=0x80, el renderer debería retornar temprano sin dibujar (comportamiento DMG estricto), pero gracias al hack, continúa y dibuja los 160*144 píxeles de la pantalla. Esto permite que juegos CGB como Tetris DX que escriben LCDC=0x80 puedan mostrar gráficos en nuestro emulador.

Fuentes Consultadas

• Pan Docs: LCD Control Register (LCDC) - Bits del registro LCDC
• Pan Docs: Scrolling - Registros SCX y SCY
• Pan Docs: Game Boy Color Registers - Diferencias CGB vs DMG en LCDC

Integridad Educativa

Próximos Pasos

• [ ] Probar Tetris DX con el hack del Bit 0 y verificar que se muestran gráficos
• [ ] Verificar que el scroll funciona correctamente en el juego (animaciones, desplazamiento de fondo)
• [ ] Implementar Window (WX/WY) para soportar ventanas superpuestas
• [ ] Implementar Sprites (OAM) para renderizar objetos móviles
• [ ] Investigar especificación exacta del Bit 0 en CGB para implementar modo CGB completo