vibe3_physics/source/ui/help_overlay.h

#pragma once

#include <SDL3/SDL.h>

#include <string>
#include <vector>

class ThemeManager;
class TextRenderer;

/**
 * @class HelpOverlay
 * @brief Overlay de ayuda con listado de controles de teclado
 *
 * Muestra un recuadro cuadrado centrado con todas las teclas y sus funciones.
 * Usa los colores del tema actual (como las notificaciones).
 * Toggle on/off con tecla H. La simulación continúa en el fondo.
 */
class HelpOverlay {
   public:
    HelpOverlay();
    ~HelpOverlay();

    /**
     * @brief Inicializa el overlay con renderer y theme manager
     */
    void initialize(SDL_Renderer* renderer, ThemeManager* theme_mgr, int physical_width, int physical_height, int font_size);

    /**
     * @brief Renderiza el overlay si está visible
     */
    void render(SDL_Renderer* renderer);

    /**
     * @brief Actualiza dimensiones físicas de ventana (zoom, fullscreen, etc.)
     */
    void updatePhysicalWindowSize(int physical_width, int physical_height);

    /**
     * @brief Reinitializa el tamaño de fuente (cuando cambia el tamaño de ventana)
     */
    void reinitializeFontSize(int new_font_size);

    /**
     * @brief Actualiza font size Y dimensiones físicas de forma atómica
     * @param font_size Tamaño de fuente actual
     * @param physical_width Nueva anchura física
     * @param physical_height Nueva altura física
     */
    void updateAll(int font_size, int physical_width, int physical_height);

    /**
     * @brief Toggle visibilidad del overlay
     */
    void toggle();

    /**
     * @brief Consulta si el overlay está visible
     */
    bool isVisible() const { return visible_; }

   private:
    SDL_Renderer* renderer_;
    ThemeManager* theme_mgr_;
    TextRenderer* text_renderer_;  // Renderer de texto para la ayuda
    int physical_width_;
    int physical_height_;
    bool visible_;

    // Dimensiones calculadas del recuadro (anchura dinámica según texto, centrado)
    int box_width_;
    int box_height_;
    int box_x_;
    int box_y_;

    // Anchos individuales de cada columna (para evitar solapamiento)
    int column1_width_;
    int column2_width_;

    // Sistema de caché para optimización de rendimiento
    SDL_Texture* cached_texture_;      // Textura cacheada del overlay completo
    SDL_Color last_category_color_;    // Último color de categorías renderizado
    SDL_Color last_content_color_;     // Último color de contenido renderizado
    SDL_Color last_bg_color_;          // Último color de fondo renderizado
    bool texture_needs_rebuild_;       // Flag para forzar regeneración de textura

    // Calcular dimensiones del texto más largo
    void calculateTextDimensions(int& max_width, int& total_height);

    // Calcular dimensiones del recuadro según tamaño de ventana y texto
    void calculateBoxDimensions();

    // Regenerar textura cacheada del overlay
    void rebuildCachedTexture();

    // Estructura para par tecla-descripción
    struct KeyBinding {
        const char* key;
        const char* description;
    };

    // Lista de todos los controles (se llena en constructor)
    std::vector<KeyBinding> key_bindings_;
};