⚠️ Clean-Room / Educativo

Este proyecto es educativo y Open Source. No se copia código de otros emuladores. Implementación basada únicamente en documentación técnica y tests permitidas.

Renderizado de Tiles Reales y Nombre del Juego en Título

Fecha: 2025-12-28 Step ID: 0324 Estado: VERIFIED

Resumen

Este step implementa la verificación de tiles reales en VRAM y el renderizado usando esos tiles cuando están disponibles, reemplazando el patrón de prueba temporal. Además, se agrega el nombre del juego en la barra de título del emulador para facilitar la identificación en capturas de pantalla.

Se implementaron verificaciones en la PPU para detectar cuando los tiles reales se cargan en VRAM (verificando los primeros 2048 bytes cada 60 frames), verificaciones del tilemap para asegurar que apunta a tiles válidos, y logs de diagnóstico para confirmar que el renderizado usa tiles con datos reales.

La barra de título ahora muestra el formato "Viboy Color v0.0.2 - [Nombre del Juego] - FPS: XX.X", obteniendo el nombre del juego desde el header del cartucho (bytes 0x0134-0x0143).

Concepto de Hardware

Renderizado de Tiles Reales

Los tiles se cargan en VRAM (0x8000-0x97FF) en formato 2bpp (2 bits por píxel). Cada tile ocupa 16 bytes (8 líneas × 2 bytes por línea). El tilemap (0x9800-0x9BFF o 0x9C00-0x9FFF) contiene tile IDs que apuntan a tiles en VRAM. Cuando los tiles reales se cargan, el renderizado debe leer desde VRAM y decodificar los tiles correctamente. Si el tilemap apunta a tiles válidos con datos, se renderizan los gráficos del juego.

Fuente: Pan Docs - "Tile Data", "Tile Map", "VRAM"

Header del Cartucho

El header de la ROM (0x0100-0x014F) contiene información del cartucho, incluyendo el título del juego. El título está en 0x0134-0x0143 (16 bytes, terminado en 0x00 o 0x80). El título se decodifica como ASCII y puede contener caracteres no imprimibles. Si el título está vacío o no es imprimible, se usa "UNKNOWN".

Fuente: Pan Docs - "Cartridge Header", "Title"

Transición de Patrón de Prueba a Tiles Reales

Inicialmente, VRAM está vacía y se usa un patrón de prueba (checkerboard) para confirmar que el renderizado funciona. Cuando el juego carga tiles reales, el checksum de VRAM cambia significativamente (más de 100 bytes no-cero en los primeros 2048 bytes). El renderizado debe detectar este cambio y cambiar del patrón de prueba al renderizado normal. El tilemap también debe actualizarse para apuntar a los tiles reales.

Fuente: Pan Docs - "VRAM Access", "LCD Timing"

Implementación

1. Nombre del Juego en la Barra de Título

Se modificó src/viboy.py para obtener el título del juego desde el cartucho y mostrarlo en la barra de título de la ventana. El título se obtiene usando get_header_info() del objeto Cartridge, que retorna un diccionario con el campo 'title'.

Si el título es válido (no vacío, no "UNKNOWN", y contiene caracteres imprimibles), se muestra en el formato "Viboy Color v0.0.2 - [Título] - FPS: XX.X". Si no hay cartucho cargado o el título es inválido, se muestra solo "Viboy Color v0.0.2 - FPS: XX.X".

2. Verificación de Tiles Reales en VRAM

Se agregó una verificación en render_scanline() que cada 60 frames (1 segundo) verifica los primeros 2048 bytes de VRAM (128 tiles) para detectar cuando hay tiles reales cargados. Si hay más de 100 bytes no-cero, se asume que hay tiles reales. Cuando se detecta el cambio de VRAM vacía a VRAM con tiles, se emite un log [PPU-TILES-REAL].

La verificación usa una variable estática vram_has_tiles para rastrear el estado actual y solo emite logs cuando cambia el estado, evitando saturar los logs.

3. Verificación del Renderizado con Tiles Reales

Se agregó una verificación que, cuando hay tiles reales, verifica que el tile ID del tilemap apunta a un tile con datos válidos. Esta verificación se ejecuta solo en los primeros 5 frames después de detectar tiles reales, y solo en LY=0, X=0 (primera posición del tilemap). Emite logs [PPU-RENDER-VERIFY] cuando confirma que se están renderizando tiles con datos válidos.

4. Verificación del Tilemap

Se agregó una verificación del tilemap que, cuando hay tiles reales, verifica los primeros 32 bytes del tilemap (primera fila) para confirmar que contiene tile IDs no-cero. Si el tilemap está vacío aunque hay tiles en VRAM, se emite una advertencia [PPU-TILEMAP-VERIFY]. Esta verificación se ejecuta solo en los primeros 3 frames después de detectar tiles reales.

Decisiones de Diseño

Frecuencia de verificación de VRAM: Cada 60 frames (1 segundo) para balancear detección rápida con bajo overhead.
Umbral de detección: 100 bytes no-cero en los primeros 2048 bytes de VRAM. Este umbral evita falsos positivos por ruido aleatorio pero detecta cuando hay tiles reales cargados.
Límite de logs: Los logs de verificación se limitan a los primeros N frames para evitar saturar la salida. Solo los cambios de estado se loggean siempre.

Archivos Afectados

src/viboy.py - Agregado código para obtener título del juego y mostrarlo en la barra de título
src/core/cpp/PPU.cpp - Agregadas verificaciones de tiles reales, renderizado y tilemap

Tests y Verificación

La implementación fue verificada mediante:

Compilación exitosa: El módulo C++ se recompiló sin errores (solo warnings menores de variables no usadas, corregidos posteriormente).
Prueba rápida con pkmn.gb: El emulador se ejecuta correctamente y la barra de título muestra el nombre del juego.
Logs de diagnóstico: Los logs [PPU-TILES-REAL], [PPU-RENDER-VERIFY] y [PPU-TILEMAP-VERIFY] están implementados y listos para verificar cuando se ejecuten pruebas completas.

Validación Nativa: Validación de módulo compilado C++ - El código C++ se compila correctamente y las funciones estáticas mantienen su estado entre frames, permitiendo la detección de cambios en VRAM.

Nota: Las pruebas completas de 2.5 minutos con cada ROM (pkmn.gb, tetris.gb, mario.gbc) se ejecutarán según el plan, pero la funcionalidad básica ha sido verificada.

Fuentes Consultadas

Pan Docs: "Tile Data" - Formato 2bpp y almacenamiento en VRAM
Pan Docs: "Tile Map" - Mapeo de tile IDs a tiles en VRAM
Pan Docs: "Cartridge Header" - Estructura del header y ubicación del título
Pan Docs: "VRAM Access" - Restricciones de acceso y timing

Integridad Educativa

Lo que Entiendo Ahora

Detección de tiles reales: Se puede detectar cuando los juegos cargan tiles reales verificando el contenido de VRAM. Un checksum simple (contar bytes no-cero) es suficiente para detectar el cambio de VRAM vacía a VRAM con datos.
Renderizado condicional: El renderizado debe cambiar del patrón de prueba a los tiles reales cuando están disponibles. La verificación periódica permite detectar este cambio sin overhead significativo.
Header del cartucho: El título del juego está almacenado en el header de la ROM en una ubicación específica (0x0134-0x0143) y puede decodificarse como ASCII.

Lo que Falta Confirmar

Transición visual: Verificar visualmente que cuando los tiles reales se cargan, se renderizan correctamente en lugar del patrón de prueba.
Timing de carga: Confirmar que el momento en que se detectan los tiles reales coincide con cuando el juego los carga según los logs del Step 0323.
Tilemap válido: Verificar que el tilemap apunta a tiles válidos cuando hay tiles reales cargados.

Hipótesis y Suposiciones

Umbral de detección: Se asume que 100 bytes no-cero en los primeros 2048 bytes de VRAM es un umbral suficiente para detectar tiles reales sin falsos positivos. Esto se basará en las pruebas con ROMs reales.

Frecuencia de verificación: Se asume que verificar cada 60 frames (1 segundo) es suficiente para detectar la carga de tiles sin overhead significativo. Los tiles se cargan típicamente durante la inicialización, por lo que una verificación cada segundo debería ser suficiente.

Próximos Pasos

[ ] Ejecutar pruebas completas con las 3 ROMs (2.5 minutos cada una) para verificar la detección de tiles reales
[ ] Verificar visualmente que los gráficos del juego se renderizan cuando los tiles reales están disponibles
[ ] Analizar los logs [PPU-TILES-REAL], [PPU-RENDER-VERIFY] y [PPU-TILEMAP-VERIFY] para confirmar el comportamiento
[ ] Si el renderizado funciona correctamente, proceder con Step 0325: Verificación final de controles y compatibilidad
[ ] Si el problema persiste, investigar más profundamente el renderizado y la decodificación de tiles