Dynamic Bitmaps: Load images at runtime – TouchGFX

This article describes how dynamic bitmaps can be used to create applications where some of the graphic content is read from files or other input at runtime.

The "dynamic bitmap example" shows how to use 24-bit BMP-files.
An example on GitHub shows how to use LibJPEG to use JPEG-files.

This article applies only to TouchGFX release 4.5 and later

Recall that standard bitmaps are compiled into the application and therefore must be available at compile time. The bitmaps are converted from e.g. PNG files and stored in an internal format together with size and format information.

This setup makes it impossible to use the Image widget to show images obtained at runtime.

The problem can be resolved using the new dynamic bitmap feature.

Dynamic Bitmap Operations

The dynamic bitmap operations are all placed in the Bitmap class.

static BitmapId dynamicBitmapCreate(const uint16_t width, const uint16_t height, BitmapFormat format) This method creates a dynamic bitmap with the width, height and bitmap format specified. The bitmap is only created if enough unused memory is available. Returns BITMAP_INVALID if the bitmap was not created.

static bool dynamicBitmapDelete(BitmapId id) This method deletes a dynamic bitmap.

static uint8_t* dynamicBitmapGetAddress(BitmapId id) This method returns the address of the dynamic bitmap. This method is used by file loaders to copy image data into the bitmap.

static bool dynamicBitmapSetSolidRect(BitmapId id, const Rect& solidRect) This method sets the solid rectangle of a dynamic bitmap. See below.

Loading Dynamic Bitmap Example

Insert an Image widget in the view:

class TemplateView : public View
{
private:
    Image image;
}

Load the image date in setupScreen (substiture libc file operations with what your platform provides):

void TemplateView::setupScreen()
{
    FILE* f = fopen("image.jpg", "rb");
    uint16_t width, height;
    
    BMPFileLoader::getBMP24Dimensions(f, width, height);
    BitmapId bmpId;

    //Create (16bit) dynamic bitmap
    bmpId = Bitmap::dynamicBitmapCreate(width, height, Bitmap::RGB565);

    //Load BMP file
    BMPFileLoader::readBMP24File(Bitmap(bmpId), f);

    //make Image show the loaded bitmap
    image.setBitmap(Bitmap(bmpId));

    //Position image and add to View
    image.setXY(20, 20);
    add(image);
    ...
}

The BMPFileLoader class used in the example can be found in the "dynamic_bitmap_example" provided with TouchGFX.

A JPEG file loader can be found on github.

Configure memory for dynamic bitmaps

Before you can create and use dynamic bitmaps you must configure TouchGFX. It is a prerequisite to provide a buffer and the maximum number of dynamic bitmaps. You provide the parameters to touchgfx_generic_init which is typically called from BoardConfiguration.cpp (or main.cpp for the simulator).

Here is an example for STM32F7 where we allocate a buffer in external RAM:
We wish to load and show a 24-bit bitmap of size 320x240. The memory requirement is thus 320x240x3 = 230400. We also need a little space for bookkeeping, so we allocate 232000 bytes for the buffer.

static uint32_t bmpCache = (uint32_t)(0xC00C0000); // SDRAM
void touchgfx_init()
{
 HAL& hal = touchgfx_generic_init<STM32F7HAL>(dma, display,
                    tc, 480, 272, (uint16_t*)bmpCache, 232000, 1);
...

The final argument is the maximum number of dynamic bitmaps, so adjust this according to your needs.

Note that in case of insufficient memory, the BitmapId returned by dynamicBitmapCreate will be
BITMAP_INVALID.

Alpha channels for dynamic bitmaps

The dynamic bitmaps can not have separate alpha channels. If you need to load image formats with transparent pixels (e.g. PNG) you must use the bitmap format ARGB8888 where the alpha information is directly included in the pixels.

The solid rectangle is by default set to the whole bitmap for the bitmap formats RGB565, RGB888, BW, BW_RLE.

For the format ARGB888 is the default solid rectangle empty. If you load a partly transparent image from a file it can increase performance of the image drawing operation if you set solid rectangle of the dynamic bitmap after loading.