Skip to main content

Dynamic Bitmaps

This section explains how to use Dynamic Bitmaps. 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.

It is also possible to create a bitmap in RAM at runtime. This is called a dynamic bitmap. A dynamic bitmap can be used just as the static bitmaps that are compiled into the application. This means that you can use a dynamic bitmap with e.g. the Image and Button widgets.

Dynamic Bitmap Configuration​

When you create a dynamic bitmap the RAM for the pixels is allocated from the bitmap cache. You must therefore configure a bitmap cache before you can create dynamic bitmaps.

See the article on bitmap caching for configuration instructions.

It is required to define the maximum number of Dynamic Bitmaps used in your application. This maximum is passed to TouchGFX together with the bitmap cache address and size. Here we configure a bitmap cache with up to 4 dynamic bitmaps:

BoardConfiguration.cpp (extract)
// Place cache start address in SDRAM at address 0xC0008000;
uint16_t* cacheStartAddr = (uint16_t*)0xC0008000;
uint32_t cacheSize = 0x300000; //3 MB, as example
HAL& hal = touchgfx_generic_init<STM32F4HAL>(dma, display, tc, DISPLAY_WIDTH, DISPLAY_HEIGHT, cacheStartAddr, cacheSize, 4);

Using a Dynamic Bitmap Example​

To use the dynamic bitmap we need a widget to show it. So insert an Image widget in the view (in code or in the Designer):

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

Create the dynamic bitmap in setupScreen. Here we use the 16bpp format RGB565. If your framebuffer is e.g 24 bit use RGB888. To create a transparent bitmap, use the format ARGB8888:

void TemplateView::setupScreen()
{
    BitmapId bmpId;

    //Create (16bit) dynamic bitmap of size 100x150
    const int width = 100;
    const int height = 150;
    bmpId = Bitmap::dynamicBitmapCreate(100, 150, Bitmap::RGB565);

    //set all pixels white
    if (bmpId != BITMAP_INVALID)
    {
       memset(Bitmap::dynamicBitmapGetAddress(bmpId), 0xFF, width*height*2);
    }

    //Make Image widget show the dynamic bitmap
    image.setBitmap(Bitmap(bmpId));

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

If you want to load your image from a file you can replace the call to memset with your loader code. See the article Loading Images At Runtime

Dynamic Bitmap Operations​

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

Creating a Dynamic Bitmap​

The following method creates a dynamic bitmap with the width, height and bitmap format specified. The bitmap is only created if enough unused memory is available. The method returns BITMAP_INVALID if the bitmap was not created.

static BitmapId Bitmap::dynamicBitmapCreate(const uint16_t width, const uint16_t height, BitmapFormat format)

Deleting a Dynamic Bitmap​

This method deletes a dynamic bitmap.

static bool Bitmap::dynamicBitmapDelete(BitmapId id)

Get the address of the pixels in a Dynamic Bitmap​

The following method returns the address of the dynamic bitmap. This method is used by file loaders to copy image data into the bitmap.

static uint8_t* dynamicBitmapGetAddress(BitmapId id)

Set the solid area of a Dynamic Bitmap​

The following method sets the solid rectangle of a dynamic bitmap.

static bool dynamicBitmapSetSolidRect(BitmapId id, const Rect& solidRect)

Read more about the "solid area" concept in the Custom Widgets article.

By default the solid area is set to be the whole bitmap for non-transparent formats like RGB565 and RGB888. It is set to empty for transparent formats like ARGB8888.