Imágenes en LVGL 9: arrays C, PNG y migración desde v8

En LVGL 9, un recurso de imagen convertido se describe con lv_image_dsc_t. Crea un objeto de imagen con lv_image_create() y después pasa la dirección del descriptor a lv_image_set_src(). El archivo C que contiene ese descriptor también debe formar parte de la compilación del firmware.

Si tu ejemplo usa lv_img_dsc_t y lv_img_set_src(), comprueba su versión antes de copiarlo. Esos son los nombres usados en los tutoriales de LVGL 8.

Comprueba la versión en ambos extremos

Hay dos versiones que deben coincidir: la biblioteca en tu firmware y el convertidor que produjo el recurso. Una llamada a función de v9 no repara un descriptor generado para un formato distinto.

Task	LVGL 8 names	LVGL 9 names
Describe an image	lv_img_dsc_t	lv_image_dsc_t
Declare an external image	LV_IMG_DECLARE	LV_IMAGE_DECLARE
Create an image object	lv_img_create	lv_image_create
Set its source	lv_img_set_src	lv_image_set_src

La referencia de imágenes de LVGL 8 oficial y la referencia de imágenes de LVGL 9 muestran las API respectivas. Puede haber alias de compatibilidad en una compilación concreta, pero usar una versión de forma coherente hace que la integración sea más fácil de inspeccionar.

Añade una imagen convertida a LVGL 9

Supón que tu convertidor generó status_logo.c y que el descriptor dentro de él se llama status_logo. Añade ese archivo a los archivos fuente compilados por tu proyecto. Después usa esta función de integración tras inicializar LVGL y la pantalla:

#include "lvgl.h"

LV_IMAGE_DECLARE(status_logo);

void add_status_logo(lv_obj_t *parent)
{
    lv_obj_t *image = lv_image_create(parent);
    lv_image_set_src(image, &status_logo);
    lv_obj_align(image, LV_ALIGN_TOP_LEFT, 12, 12);
}

El nombre debe coincidir con el símbolo dentro del archivo generado, que puede diferir del nombre de archivo. Este ejemplo ofrece código de integración, no los datos de píxel del logotipo.

Compila el recurso una vez. Incluir un archivo .c directamente mientras también lo compilas por separado puede definir el mismo símbolo dos veces. Una declaración externa hace visible el símbolo; no aporta su definición.

Por qué importa el descriptor

Un puntero a los píxeles de una imagen no le dice a LVGL sus dimensiones ni su formato de color. El descriptor lleva esa información junto al puntero de datos y el tamaño. Los campos exactos se definen en el encabezado del descriptor de imagen de LVGL 9.2.

Mantén intacto el descriptor generado por el convertidor al probar. Editar su ancho para estirar una imagen cambia cómo se interpretan los datos; no remuestrea los píxeles. Regenera el recurso con las dimensiones deseadas en su lugar.

Para una primera comprobación, usa una imagen pequeña con un borde visible y una marca asimétrica en una esquina. Es más fácil detectar recortes, orientación y filas que faltan que con un fondo uniforme.

Un archivo PNG necesita una ruta distinta

LVGL puede usar variables de imagen u orígenes respaldados por archivos, pero esas rutas tienen requisitos distintos. Un recurso C convertido en bruto ya contiene datos de píxel. Un archivo .png todavía necesita un decodificador adecuado, y un origen en sistema de archivos también necesita acceso a almacenamiento configurado en el firmware. La guía de almacenamiento de imágenes explica esa distinción.

Para un logotipo de estado fijo, un recurso compilado suele ser sencillo de gestionar. Para imágenes que los usuarios sustituyen en una tarjeta SD, una ruta respaldada por archivos puede encajar mejor con el producto. Mantén disponible una imagen compilada que sepas que funciona mientras pones en marcha el sistema de archivos y el decodificador, para que un widget vacío no te deje depurándolo todo a la vez.

Usar Lopaka para el recurso y el diseño

La documentación de plataformas actual de Lopaka identifica v9 como su destino de API C de LVGL. También documenta recursos de imagen descargables. Ajusta esa salida a la versión de LVGL que ya usa el firmware de tu placa.

El editor se encarga del diseño de la pantalla. La inicialización de la pantalla, los controladores de almacenamiento, el manejo de entradas y el comportamiento de la aplicación siguen perteneciendo a tu firmware. Si primero estás eligiendo un flujo de trabajo de pantalla, empieza con la guía del constructor de GUI para ESP32.

Preguntas comunes

¿Por qué obtengo una referencia indefinida a mi imagen?

Comprueba que el recurso generado se compile y que su símbolo exportado coincida con la declaración. En un proyecto mixto C/C++, comprueba también el enlace en el límite de la declaración.

¿Puedo renombrar lv_img_dsc_t a lv_image_dsc_t?

Regenera para la versión de LVGL prevista. Renombrar solo el tipo no garantiza que la disposición del encabezado, las constantes de color y la carga sean compatibles.

¿Por qué la imagen aparece con dimensiones incorrectas?

Compara las dimensiones de origen, las dimensiones convertidas, el descriptor y los ajustes del widget. Corrige la primera discrepancia que encuentres y después vuelve a probar el mismo recurso pequeño.