Imágenes TFT_eSPI: corrige los colores RGB565 y el orden de bytes

Si una imagen tiene la forma correcta pero los colores incorrectos en TFT_eSPI, prueba dos cosas por separado: la configuración RGB/BGR de la pantalla y el orden de bytes de los datos de imagen. Cambiar ambas a la vez hace difícil saber qué ajuste resolvió el problema.

Un patrón pequeño es más útil aquí que una fotografía. El rojo, el verde, el azul, el blanco y el negro te dan valores que puedes reconocer sin adivinar cómo era la imagen original.

Dibuja primero colores sólidos

Añade esta función a un sketch que ya inicialice la pantalla correctamente. Llámala después de tft.init() y de tu ajuste de rotación. Supone que el objeto de pantalla se llama tft y que la pantalla tiene al menos 100 × 20 píxeles.

void drawColorReference() {
    const uint16_t colors[] = {
        TFT_RED, TFT_GREEN, TFT_BLUE, TFT_WHITE, TFT_BLACK
    };

    for (int i = 0; i < 5; ++i) {
        tft.fillRect(i * 20, 0, 20, 20, colors[i]);
    }
}

Patrón de prueba sintético, 100 × 20: cinco bandas iguales: rojo, verde, azul, blanco, negro. No es una fotografía de hardware. Descarga el PNG de referencia y conviértelo con tu convertidor para comparar la ruta del recurso con el renderizado de colores sólidos.

Si estos rectángulos están mal, trabaja en la configuración de la pantalla antes de convertir otra imagen. El controlador elegido, las dimensiones del panel y el orden de color pertenecen a la configuración de hardware. El archivo User_Setup.h de TFT_eSPI documenta las opciones relevantes, incluida TFT_RGB_ORDER para los controladores compatibles.

Si el rojo aparece azul y el azul aparece rojo mientras el verde se mantiene verde, el orden RGB/BGR es un sospechoso útil. Comprueba la configuración del panel real en lugar de suponer que todos los módulos vendidos con el mismo nombre de controlador se comportan igual.

Después prueba la ruta de imagen

Cuando los rectángulos sólidos sean correctos, envía un array RGB565 mediante pushImage(). Este segundo patrón se dibuja más abajo en la pantalla, así que deja al menos 100 × 32 píxeles en total:

void drawImageReference() {
    static const uint16_t strip[] = {
        0xF800, 0x07E0, 0x001F, 0xFFFF, 0x0000,
        0xF800, 0x07E0, 0x001F, 0xFFFF, 0x0000
    };

    const bool previous = tft.getSwapBytes();
    tft.setSwapBytes(false);
    tft.pushImage(0, 24, 5, 2, strip);
    tft.setSwapBytes(true);
    tft.pushImage(0, 30, 5, 2, strip);
    tft.setSwapBytes(previous);
}

Esto produce dos patrones diminutos de 5 × 2, uno con cada ajuste de intercambio. Inspecciona cuál coincide con los colores de referencia. Usa una lupa si hace falta; mantener el array pequeño hace que cada valor sea fácil de auditar.

La biblioteca declara setSwapBytes() específicamente para el orden de bytes de píxel en su encabezado de API. El ajuste correcto depende de cómo se almacena el recurso y de qué ruta de API lo lee. Trata el resultado como una comprobación para esa representación del recurso, no como un ajuste universal para cada bitmap del proyecto.

Intercambiar bytes no es intercambiar rojo y azul

En RGB565, el rojo es 0xF800. Sus bytes son F8 y 00; invertirlos produce 0x00F8. Eso cambia el valor numérico compactado. No intercambia simplemente los canales rojo y azul.

Por eso dos síntomas necesitan comprobaciones distintas:

What you see	What to check first
Solid red and blue rectangles are exchanged	Panel RGB/BGR configuration
Solid rectangles look right, imported colors look wrong	Asset encoding and byte order
Rows wrap or form diagonal strips	Width, height, and array length
Everything is blank, including solid rectangles	Display initialization, wiring, backlight, and driver

Exporta el recurso para TFT_eSPI

En Lopaka, selecciona TFT_eSPI antes de importar la imagen y después exporta los datos con su llamada de dibujo generada. Si cambias la biblioteca de destino más tarde, regenera el recurso en lugar de llevar el array de bytes antiguo al firmware nuevo.

Para el flujo completo de diseño, usa la guía de UI para pantallas TFT personalizadas. La guía de integración de TFT_eSPI cubre la configuración de hardware y el código de dibujo generado.

Prepara primero el patrón de diagnóstico, después tu logotipo y después la pantalla completa. Si solo falla la pantalla completa, has reducido el problema a ese recurso o a la ruta de memoria que usa.

Preguntas comunes

¿Debo llamar siempre a setSwapBytes(true)?

No. Ajusta la configuración al array y a la ruta de dibujo. Restáurala tras una prueba local para que el renderizado posterior no herede una configuración que olvidaste.

¿Puede un array RGB565 conservar la transparencia de un PNG?

RGB565 no tiene componente alfa. Un PNG transparente necesita un fondo elegido o un método de dibujo con compatibilidad explícita con transparencia. Un borde oscuro alrededor de un logotipo puede deberse a aplanarlo contra el fondo equivocado.

¿Es distinto para ST7789 e ILI9341?

La prueba funciona con cualquiera de los dos cuando TFT_eSPI ya controla el panel. Sus detalles de configuración siguen siendo distintos. Mantén la configuración del panel que hace correctos los colores sólidos y después diagnostica los recursos importados por separado.