[thomaskistler]

Fixes: N/A (feature; no linked issue). Alternative to #7947, which adds a bitmap source to lvgl.image.

Summary of changes:

Adds lvgl.bitmap([parent, ]params), a separate Lua LVGL object (also lvgl.BITMAP for lvgl.build) that wraps StaticBitmap. lvgl.image is not modified.

local tile = lvgl.bitmap({ file = "/IMAGES/tile.jpg", x = 0, y = 0, w = 256, h = 256 })
tile:set({ file = "/IMAGES/other.jpg" })

Motivation

lvgl.image decodes through LVGL's shared image cache, which has 8 entries (LV_IMG_CACHE_DEF_SIZE). A Lua widget that shows more images than that, for example a map made of 256x256 JPEG tiles, keeps evicting images that are still visible and decodes them again on redraw. lvgl.bitmap decodes once when its file changes and the object owns the pixels, so a widget can keep one object per image and decide for itself which ones stay decoded.

Details

• file is a string or a function, like lvgl.image. The file is only decoded when it changes. A function is only called while the object is visible. Setting a string replaces a previous function.
• The image is scaled to fit the frame when it is decoded and centered. Changing w/h reloads it. Hidden objects keep their pixels.
• StaticBitmap::setSource(filename) now chooses the format from the file like BitmapBuffer::loadBitmap: RGB565 for opaque images, ARGB4444 for images with alpha. setSource(filename, fmt) forces a format, and the constructor takes the same optional format. Existing callers (model select, file preview, model bitmap widget) pass BMP_ARGB4444 explicitly, so their rendering does not change.
• Previously StaticBitmap always used ARGB4444, which keeps 4 bits per channel and stores 3 bytes per pixel. For an opaque JPEG tile, an ad-hoc host measurement gave 192 KB and 31.1 dB against the 8-bit decode, versus 128 KB and 39.9 dB for RGB565. With the format chosen from the file, opaque images are byte-identical to what Bitmap.open produces.
• The pixel memory is not counted against the Lua bitmap memory limit (LUA_MEM_EXTRA_MAX).
• A file that cannot be loaded leaves the object blank.
• ETX_BITMAP is inserted after ETX_QRCODE, so the numeric values of later lvgl.* type constants shift by one.
• Documentation is in the lvgl.bitmap luadoc block. It is marked as introduced in 3.0.0.

Validation

Built and tested the native TX16S target on macOS:

• cmake -DCMAKE_BUILD_TYPE=Debug -DPCB=X10 -DPCBREV=TX16S .. in build/, then cmake --build . --target native-configure and cmake --build native --target gtests-radio
• native/gtests-radio: 259 tests passed, including 17 new LuaLvglBitmap tests

Not done: ARM firmware and Companion builds, and testing on a radio.