ViBe1 Delta - Simulador de Sprites con Fisica

ViBe1 Delta es un programa de demostracion que utiliza SDL3 para mostrar sprites (pelotas) rebotando en pantalla con simulacion de fisica basica. Este proyecto sirve como base para experimentar con bucles de juego, renderizado y fisica en tiempo real.

🎯 Caracteristicas Actuales

• Simulacion de fisica: Gravedad, rebotes y colisiones con perdida de energia
• Multiples escenarios: 8 configuraciones predefinidas (1 a 100,000 pelotas)
• Sistema de temas visuales: 4 temas de colores con fondos degradados y paletas tematicas
• Interactividad: Controles de teclado para modificar el comportamiento
• Renderizado batch optimizado: Sistema de batch rendering con SDL_RenderGeometry para 50K+ sprites
• Colores tematicos: Paletas de 8 colores por tema aplicadas proceduralmente
• Monitor de rendimiento: Contador FPS en tiempo real
• Control V-Sync: Activacion/desactivacion dinamica del V-Sync

🎮 Controles

Tecla	Accion
H	Alternar debug display (FPS, V-Sync, valores fisica)
V	Alternar V-Sync ON/OFF
F1-F4	Seleccion directa de tema de colores (Atardecer/Oceano/Neon/Bosque)
T	Ciclar entre temas de colores
1-8	Cambiar numero de pelotas (1, 10, 100, 500, 1K, 10K, 50K, 100K)
ESPACIO	Impulsar todas las pelotas hacia arriba
G	Alternar direccion de la gravedad
ESC	Salir del programa

📊 Informacion en Pantalla

• Centro: Numero de pelotas activas en blanco (temporal)
• Centro: Nombre del tema activo en color tematico (temporal, debajo del contador)

Debug Display (Tecla H)

Cuando se activa el debug display con la tecla H:

• Esquina superior izquierda: Estado V-Sync (VSYNC ON/OFF) en cian
• Esquina superior derecha: Contador FPS en tiempo real en amarillo
• Lineas 3-5: Valores fisica primera pelota (GRAV, VY, FLOOR) en magenta
• Linea 6: Tema activo (THEME SUNSET/OCEAN/NEON/FOREST) en amarillo claro

🎨 Sistema de Temas de Colores

ViBe1 Delta incluye 4 temas visuales que transforman completamente la apariencia del simulador:

Temas Disponibles

Tecla	Tema	Descripcion	Fondo	Paleta de Pelotas
F1	ATARDECER	Colores calidos de puesta de sol	Degradado naranja-rojo	Tonos naranjas, rojos y amarillos
F2	OCEANO	Ambiente marino refrescante	Degradado azul-cian	Azules, cianes y verdes agua
F3	NEON	Colores vibrantes futuristas	Degradado magenta-cian	Magentas, cianes y rosas brillantes
F4	BOSQUE	Naturaleza verde relajante	Degradado verde oscuro-claro	Verdes naturales y tierra

Controles de Temas

• Seleccion directa: Usa F1, F2, F3 o F4 para cambiar inmediatamente al tema deseado
• Ciclado secuencial: Presiona T para avanzar al siguiente tema en orden
• Indicador visual: El nombre del tema aparece temporalmente en el centro de la pantalla con colores tematicos
• Regeneracion automatica: Las pelotas adoptan automaticamente la nueva paleta de colores al cambiar tema

Detalles Tecnicos

• Fondos degradados: Implementados con SDL_RenderGeometry usando vertices con colores interpolados
• Paletas tematicas: 8 colores unicos por tema aplicados aleatoriamente a las pelotas
• Rendimiento optimizado: El cambio de tema solo regenera los colores, manteniendo la fisica
• Compatibilidad completa: Funciona con todos los escenarios (1 a 100,000 pelotas)

🏗️ Estructura del Proyecto

vibe_delta/
├── source/
│   ├── main.cpp        # Bucle principal y logica del juego
│   ├── ball.h/cpp      # Clase Ball - logica de las pelotas
│   ├── defines.h       # Constantes y configuracion
│   └── external/       # Utilidades y bibliotecas externas
│       ├── sprite.h/cpp    # Clase Sprite - renderizado de texturas
│       ├── texture.h/cpp   # Clase Texture - gestion de imagenes
│       ├── dbgtxt.h        # Sistema de debug para texto en pantalla
│       └── stb_image.h     # Biblioteca para cargar imagenes
├── resources/
│   └── ball.png        # Textura de la pelota (10x10 pixeles)
├── CMakeLists.txt      # Configuracion de CMake
├── Makefile           # Configuracion de Make
├── CLAUDE.md          # Seguimiento de desarrollo
└── .gitignore         # Archivos ignorados por Git

🔧 Requisitos del Sistema

• SDL3 (Simple DirectMedia Layer 3)
• C++20 compatible compiler
• CMake 3.20+ o Make
• Plataforma: Windows, Linux, macOS

Instalacion de SDL3

Windows (MinGW)

# Usando vcpkg o compilar desde fuente
vcpkg install sdl3

Linux

# Ubuntu/Debian
sudo apt install libsdl3-dev
# Arch Linux
sudo pacman -S sdl3

macOS

brew install sdl3

🚀 Compilacion

Opcion 1: CMake (Recomendado)

mkdir build && cd build
cmake ..
make

Opcion 2: Make directo

make

▶️ Ejecucion

# Desde la raiz del proyecto
./vibe1_delta        # Linux/macOS
./vibe1_delta.exe    # Windows

📊 Detalles Tecnicos

Configuracion Actual

• Resolucion: 320x240 pixeles (escalado x3 = 960x720)
• Sistema de timing: Delta time independiente del framerate
• Fisica: Gravedad constante (0.2f), rebotes con perdida de energia
• Tamaño de pelota: 10x10 pixeles
• V-Sync: Activado por defecto, controlable dinamicamente

Arquitectura del Codigo

1. main.cpp: Contiene el bucle principal con cuatro fases:

   • calculateDeltaTime(): Calcula tiempo transcurrido entre frames
   • update(): Actualiza la logica del juego usando delta time + calculo FPS
   • checkEvents(): Procesa eventos de entrada
   • render(): Renderiza la escena + overlays informativos

2. Ball: Maneja la fisica de cada pelota individual con timing basado en delta time

3. Sprite: Sistema de renderizado de texturas con filtro nearest neighbor

4. Texture: Gestion de carga y renderizado de imagenes con filtro pixel-perfect

✅ Migracion a Delta Time (COMPLETADO)

Sistema Anterior (Frame-Based)

El sistema original estaba acoplado a 60 FPS con logica dependiente del framerate:

// Sistema ANTIGUO en update()
if (SDL_GetTicks() - ticks > DEMO_SPEED) { // DEMO_SPEED = 1000/60 = 16.67ms
    // Solo aqui se actualizaba la fisica cada 16.67ms
    for (auto &ball : balls) {
        ball->update(); // Sin parametros de tiempo
    }
    ticks = SDL_GetTicks();
}

Problemas del sistema anterior:

• Velocidad inconsistente entre diferentes refresh rates (60Hz vs 75Hz vs 144Hz)
• Logica de fisica acoplada a framerate fijo
• V-Sync ON/OFF cambiaba la velocidad del juego
• Rendimiento inconsistente en diferentes hardware

Sistema Actual (Delta Time)

Implementacion delta time para simulacion independiente del framerate:

// Sistema NUEVO - Variables globales
Uint64 last_frame_time = 0;
float delta_time = 0.0f;

// Calculo de delta time
void calculateDeltaTime() {
    Uint64 current_time = SDL_GetTicks();
    if (last_frame_time == 0) {
        last_frame_time = current_time;
        delta_time = 1.0f / 60.0f; // Primer frame a 60 FPS
        return;
    }

    delta_time = (current_time - last_frame_time) / 1000.0f; // Convertir a segundos
    last_frame_time = current_time;

    // Limitar delta time para evitar saltos grandes
    if (delta_time > 0.05f) {
        delta_time = 1.0f / 60.0f; // Fallback a 60 FPS
    }
}

// Bucle principal actualizado
while (!should_exit) {
    calculateDeltaTime();  // 1. Calcular tiempo transcurrido
    update();             // 2. Actualizar logica (usa delta_time)
    checkEvents();        // 3. Procesar entrada
    render();            // 4. Renderizar escena
}

Conversion de Fisica: Frame-Based → Time-Based

1. Conversion de Velocidades

// En Ball::Ball() constructor
// ANTES: velocidades en pixeles/frame
vx_ = vx;
vy_ = vy;

// AHORA: convertir a pixeles/segundo (x60)
vx_ = vx * 60.0f;
vy_ = vy * 60.0f;

2. Conversion de Gravedad (Aceleracion)

// En Ball::Ball() constructor
// ANTES: gravedad en pixeles/frame²
gravity_force_ = GRAVITY_FORCE;

// AHORA: convertir a pixeles/segundo² (x60²)
gravity_force_ = GRAVITY_FORCE * 60.0f * 60.0f; // 3600x multiplicador

¿Por que 60² para gravedad?

• Velocidad: pixeles/frame * frame/segundo = pixeles/segundo → x60
• Aceleracion: pixeles/frame² * frame²/segundo² = pixeles/segundo² → x60²

3. Aplicacion de Delta Time en Fisica

// En Ball::update(float deltaTime)
// ANTES: incrementos fijos por frame
vy_ += gravity_force_;
pos_.x += vx_;
pos_.y += vy_;

// AHORA: incrementos proporcionales al tiempo transcurrido
vy_ += gravity_force_ * deltaTime;  // Aceleracion * tiempo
pos_.x += vx_ * deltaTime;         // Velocidad * tiempo
pos_.y += vy_ * deltaTime;

Valores de Debug: Antes vs Ahora

Parametro	Sistema Anterior	Sistema Delta Time	Razon
Velocidad X/Y	1.0 - 3.0 pixeles/frame	60.0 - 180.0 pixeles/segundo	x60 conversion
Gravedad	0.2 pixeles/frame²	720.0 pixeles/segundo²	x3600 conversion
Debug Display	No disponible	GRAV: 720.000000 VY: -140.5 FLOOR: NO	Valores en tiempo real

Beneficios Conseguidos

• ✅ Velocidad consistente entre 60Hz, 75Hz, 144Hz y otros refresh rates
• ✅ V-Sync independiente: misma velocidad con V-Sync ON/OFF
• ✅ Fisica precisa: gravedad y movimiento calculados correctamente
• ✅ Escalabilidad: preparado para futuras optimizaciones
• ✅ Debug en tiempo real: monitoreo de valores de fisica

Sistema de Debug Implementado

// Debug display para primera pelota
if (!balls.empty()) {
    std::string debug_text = "GRAV: " + std::to_string(balls[0]->getGravityForce()) +
                           " VY: " + std::to_string(balls[0]->getVelocityY()) +
                           " FLOOR: " + (balls[0]->isOnFloor() ? "YES" : "NO");
    dbg_print(8, 24, debug_text.c_str(), 255, 0, 255); // Magenta
}

🚀 Sistema de Batch Rendering

Problema Original

El renderizado individual de sprites era el principal cuello de botella:

• 50,000 bolas: 50,000 llamadas SDL_RenderTexture() por frame
• Resultado: ~10 FPS (inutilizable)

Solución Implementada: SDL_RenderGeometry

Batch rendering que agrupa todos los sprites en una sola llamada:

// Recopilar datos de todas las bolas
for (auto &ball : balls) {
    SDL_FRect pos = ball->getPosition();
    Color color = ball->getColor();
    addSpriteToBatch(pos.x, pos.y, pos.w, pos.h, color.r, color.g, color.b);
}

// Renderizar TODAS las bolas en una sola llamada
SDL_RenderGeometry(renderer, texture->getSDLTexture(),
                   batch_vertices.data(), batch_vertices.size(),
                   batch_indices.data(), batch_indices.size());

Arquitectura del Batch

1. Vértices: 4 vértices por sprite (quad) con posición, UV y color
2. Índices: 6 índices por sprite (2 triángulos)
3. Acumulación: Todos los sprites se acumulan en vectores globales
4. Renderizado: Una sola llamada SDL_RenderGeometry por frame

Rendimiento Conseguido

• 50,000 bolas: >75 FPS constante (mejora de 750%)
• 100,000 bolas: Fluido y jugable
• Escalabilidad: Preparado para renderizado masivo de sprites

🛠️ Desarrollo

Para contribuir al proyecto:

1. Fork del repositorio
2. Crear rama de feature (git checkout -b feature/nueva-caracteristica)
3. Commit de cambios (git commit -am 'Añadir nueva caracteristica')
4. Push a la rama (git push origin feature/nueva-caracteristica)
5. Crear Pull Request

📝 Notas Tecnicas

• El proyecto usa smart pointers (unique_ptr, shared_ptr) para gestion de memoria
• RAII para recursos SDL
• Separacion de responsabilidades entre clases
• Configuracion multiplataforma (Windows, Linux, macOS)
• Filtro nearest neighbor para texturas pixel-perfect
• Sistema de metricas en tiempo real (FPS, V-Sync)

🐛 Problemas Conocidos

• FPS drops significativos con >10,000 pelotas
• Timing dependiente del framerate (solucion en desarrollo)
• Sin interpolacion en el renderizado

---

Proyecto desarrollado como base para experimentacion con game loops y fisica en tiempo real usando SDL3.