/**
 * @file st7789.h
 * @brief ST7789 Display-Treiber für Waveshare ESP32-S3-Touch-LCD-2
 *
 * Dieser Treiber steuert das 2.0" TFT-Display (240×320 Pixel) über SPI.
 *
 * Hardware-Details:
 * - Controller: ST7789V2
 * - Auflösung: 320×240 Pixel (Landscape-Modus)
 * - Farbtiefe: 16-bit RGB565
 * - Interface: 4-Wire SPI
 * - Maximale SPI-Frequenz: 80 MHz
 * - DMA-Unterstützung für schnelle Framebuffer-Transfers
 *
 * Features:
 * - Hardware-Reset über GPIO
 * - PWM-Hintergrundbeleuchtung (0-100%)
 * - Optimierte Framebuffer-Funktion (preswapped)
 * - DMA-basierte SPI-Transfers für hohe Performance
 */

#pragma once

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief ST7789 Display initialisieren
 * @return ESP_OK bei Erfolg, Fehlercode sonst
 *
 * Diese Funktion:
 * - Initialisiert SPI-Bus (80 MHz)
 * - Führt Hardware-Reset durch
 * - Sendet Initialisierungs-Kommandos
 * - Konfiguriert Display-Orientierung (Landscape)
 * - Aktiviert Display
 */
esp_err_t st7789_init(void);

/**
 * @brief Hintergrundbeleuchtung einstellen
 * @param brightness Helligkeit (0-100%)
 *
 * Verwendet LEDC PWM für stufenlose Helligkeitsregelung.
 * 0 = Aus, 100 = Maximale Helligkeit
 */
void st7789_set_backlight(uint8_t brightness);

/**
 * @brief Bildschirm mit Farbe füllen
 * @param color 16-bit RGB565 Farbe
 *
 * Füllt den gesamten Bildschirm (320×240) mit einer Vollfarbe.
 * Nützlich für Splash-Screens oder Hintergrund.
 *
 * RGB565 Format: RRRRR GGGGGG BBBBB
 * Beispiele:
 *   0xF800 = Rot, 0x07E0 = Grün, 0x001F = Blau
 *   0xFFFF = Weiß, 0x0000 = Schwarz
 */
void st7789_fill_screen(uint16_t color);

/**
 * @brief Einzelnes Pixel zeichnen
 * @param x X-Koordinate (0-319)
 * @param y Y-Koordinate (0-239)
 * @param color 16-bit RGB565 Farbe
 *
 * Langsame Funktion! Nur für einzelne Pixel verwenden.
 * Für größere Bereiche st7789_draw_buffer() nutzen.
 */
void st7789_draw_pixel(int16_t x, int16_t y, uint16_t color);

/**
 * @brief Framebuffer zeichnen (mit Byte-Swap)
 * @param buffer Zeiger auf RGB565 Framebuffer
 * @param x X-Startposition
 * @param y Y-Startposition
 * @param width Breite des Buffers (Pixel)
 * @param height Höhe des Buffers (Pixel)
 *
 * Diese Funktion führt automatisches Byte-Swapping durch:
 * RGB565 → BGR565 (ST7789 erwartet BGR-Reihenfolge)
 *
 * HINWEIS: Allokiert temporären Buffer! Für Performance
 * besser st7789_draw_buffer_preswapped() verwenden.
 */
void st7789_draw_buffer(const uint16_t *buffer, int16_t x, int16_t y,
                        int16_t width, int16_t height);

/**
 * @brief Framebuffer zeichnen (OPTIMIERT, ohne Byte-Swap)
 * @param buffer Zeiger auf vor-geswapted BGR565 Framebuffer
 * @param x X-Startposition
 * @param y Y-Startposition
 * @param width Breite des Buffers (Pixel)
 * @param height Höhe des Buffers (Pixel)
 *
 * OPTIMIERTE VERSION! Kein Byte-Swapping, keine Buffer-Allokation.
 * Der Buffer MUSS bereits BGR565-formatiert sein!
 *
 * Verwendung:
 *   uint16_t c_rgb = 0xF800;  // Rot in RGB565
 *   uint16_t c_bgr = (c_rgb >> 8) | (c_rgb << 8);  // Swap zu BGR565
 *   buffer[i] = c_bgr;  // In Buffer schreiben
 *
 * Dies ist die schnellste Methode für GameBoy-Emulation!
 * Spart ~33% CPU-Zeit im Vergleich zu draw_buffer().
 */
void st7789_draw_buffer_preswapped(const uint16_t *buffer, int16_t x, int16_t y,
                                   int16_t width, int16_t height);

/**
 * @brief Display in Sleep-Modus versetzen (für Deep Sleep)
 *
 * Diese Funktion:
 * - Schaltet Hintergrundbeleuchtung aus
 * - Sendet DISPOFF Befehl (Display aus)
 * - Sendet SLPIN Befehl (Sleep In)
 *
 * WICHTIG: Diese Funktion MUSS aufgerufen werden bevor der ESP32
 * in Deep-Sleep geht! Sonst blinkt das Display mit zufälligen Farben.
 */
void st7789_sleep(void);

#ifdef __cplusplus
}
#endif