LVGL-9-Bilder: C-Arrays, PNGs und v8-Migration

In LVGL 9 wird ein umgewandeltes Bild-Asset durch lv_image_dsc_t beschrieben. Erstelle ein Bildobjekt mit lv_image_create() und übergib dann die Adresse des Deskriptors an lv_image_set_src(). Die C-Datei, die diesen Deskriptor enthält, muss auch Teil des Firmware-Builds sein.

Wenn dein Beispiel lv_img_dsc_t und lv_img_set_src() nutzt, prüfe seine Version, bevor du es kopierst. Das sind die Namen, die in LVGL-8-Anleitungen verwendet werden.

Prüfe die Version an beiden Enden

Es gibt zwei Versionen, die übereinstimmen müssen: die Bibliothek in deiner Firmware und der Konverter, der das Asset erzeugt hat. Ein v9-Funktionsaufruf repariert keinen Deskriptor, der für ein anderes Format generiert wurde.

Aufgabe	LVGL-8-Namen	LVGL-9-Namen
Ein Bild beschreiben	lv_img_dsc_t	lv_image_dsc_t
Ein externes Bild deklarieren	LV_IMG_DECLARE	LV_IMAGE_DECLARE
Ein Bildobjekt erstellen	lv_img_create	lv_image_create
Seine Quelle setzen	lv_img_set_src	lv_image_set_src

Die offizielle LVGL-8-Bildreferenz und die LVGL-9-Bildreferenz zeigen die jeweiligen APIs. Kompatibilitäts-Aliase können in einem bestimmten Build existieren, aber eine Version durchgängig zu nutzen, macht die Integration leichter prüfbar.

Ein umgewandeltes Bild zu LVGL 9 hinzufügen

Nimm an, dein Konverter hat status_logo.c generiert und der Deskriptor darin heißt status_logo. Füge diese Datei zu den Quelldateien hinzu, die dein Projekt kompiliert. Nutze dann diese Integrationsfunktion, nachdem LVGL und das Display initialisiert sind:

#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);
}

Der Name muss zum Symbol in der generierten Datei passen, das vom Dateinamen abweichen kann. Dieses Beispiel liefert Integrationscode, nicht die Pixeldaten des Logos.

Kompiliere das Asset einmal. Eine .c-Datei direkt einzubinden, während sie auch separat kompiliert wird, kann dasselbe Symbol zweimal definieren. Eine externe Deklaration macht das Symbol sichtbar; sie liefert nicht seine Definition.

Warum der Deskriptor wichtig ist

Ein Zeiger auf Bildpixel sagt LVGL nicht, welche Maße oder welches Farbformat sie haben. Der Deskriptor trägt diese Information neben dem Datenzeiger und der Größe. Die genauen Felder sind im Header des LVGL-9.2-Bilddeskriptors definiert.

Behalte den vom Konverter generierten Deskriptor beim Testen unverändert. Seine Breite zu bearbeiten, um ein Bild zu strecken, ändert, wie die Daten interpretiert werden; es tastet die Pixel nicht neu ab. Generiere das Asset stattdessen mit den gewünschten Maßen neu.

Für eine erste Prüfung nutze ein kleines Bild mit sichtbarem Rand und einer asymmetrischen Markierung in einer Ecke. Es ist leichter, Beschneidung, Ausrichtung und fehlende Zeilen zu erkennen als bei einem gleichmäßigen Hintergrund.

Eine PNG-Datei braucht einen anderen Pfad

LVGL kann Bildvariablen oder dateibasierte Quellen nutzen, aber diese Wege haben unterschiedliche Anforderungen. Ein rohes umgewandeltes C-Asset enthält bereits Pixeldaten. Eine .png-Datei braucht noch einen geeigneten Decoder, und eine Dateisystemquelle braucht auch in der Firmware konfigurierten Speicherzugriff. Die Anleitung zur Bildspeicherung erklärt diesen Unterschied.

Für ein festes Status-Logo ist ein kompiliertes Asset oft unkompliziert zu verwalten. Für Bilder, die Nutzer auf einer SD-Karte ersetzen, kann ein dateibasierter Pfad besser zum Produkt passen. Halte ein bekanntes funktionierendes kompiliertes Bild bereit, während du Dateisystem und Decoder einrichtest, damit ein leeres Widget dich nicht alles auf einmal debuggen lässt.

Lopaka für Asset und Layout nutzen

Die aktuelle Plattformdokumentation von Lopaka nennt v9 als Ziel der LVGL-C-API. Sie dokumentiert auch herunterladbare Bild-Assets. Passe diese Ausgabe an die LVGL-Version an, die die Firmware deines Boards bereits nutzt.

Der Editor kümmert sich um das Screen-Design. Display-Initialisierung, Speichertreiber, Eingabebehandlung und Anwendungsverhalten gehören weiterhin in deine Firmware. Wenn du zuerst einen Display-Workflow auswählst, starte mit der Anleitung zum ESP32-GUI-Builder.

Häufige Fragen

Warum erhalte ich eine undefinierte Referenz auf mein Bild?

Prüfe, ob das generierte Asset kompiliert wird und ob sein exportiertes Symbol zur Deklaration passt. Prüfe in einem gemischten C/C++-Projekt auch die Verlinkung an der Deklarationsgrenze.

Kann ich lv_img_dsc_t in lv_image_dsc_t umbenennen?

Generiere für die beabsichtigte LVGL-Version neu. Nur den Typ umzubenennen, stellt nicht sicher, dass Header-Layout, Farbkonstanten und Nutzdaten kompatibel sind.

Warum erscheint das Bild mit den falschen Maßen?

Vergleiche Quellmaße, umgewandelte Maße, Deskriptor und Widget-Einstellungen. Behebe die erste Diskrepanz, die du findest, und teste dann dasselbe kleine Asset erneut.