Skip to main content

Bitmap

touchgfx/Bitmap.hpp

This class provides a proxy object for a bitmap image stored in the application specific bitmap database. The proxy provides access to the raw bitmap data as well as metadata.

Public Classes

structBitmapData
Data of a bitmap.
structCacheTableEntry
Cache bookkeeping.
structDynamicBitmapData
Data of a dynamic Bitmap.

Public Types

enumBitmapFormat { RGB565, RGB888, ARGB8888, BW, BW_RLE, GRAY2, GRAY4, ARGB2222, ABGR2222, RGBA2222, BGRA2222, L8, A4, CUSTOM }
Data of a bitmap can be stored in the following formats.
enumClutFormat { CLUT_FORMAT_L8_ARGB8888, CLUT_FORMAT_L8_RGB888, CLUT_FORMAT_L8_RGB565 }
Color data of a clut can be stored in the following formats.
enumCompression { COMPRESSION_L8_NONE = 0, COMPRESSION_L8_L4 = 1, COMPRESSION_L8_RLE = 2, COMPRESSION_L8_LZW9 = 3 }
Algorithms used for L8 images compression can be stored in the following formats.

Public Functions

Bitmap(const BitmapId id =BITMAP_INVALID)
Creates and binds a Bitmap instance to the corresponding entry in the BitmapData array.
const uint8_t *getData() const
Gets a pointer to the Bitmap data.
const uint8_t *getExtraData() const
Gets a pointer to the extra (alpha) data, if present in the Bitmap.
BitmapFormatgetFormat() const
Gets the format of how the Bitmap is stored.
int16_tgetHeight() const
Gets the height of the Bitmap in pixels.
BitmapIdgetId() const
Gets the id of this Bitmap.
RectgetRect() const
Gets the rectangle describing the dimensions of the Bitmap.
RectgetSolidRect() const
Gets the largest solid, i.e.
int16_tgetWidth() const
Gets the width of the Bitmap in pixels.
boolhasTransparentPixels() const
Query if this object has transparent pixels.
boolisAlphaPerPixel() const
Query if this object has an alpha channel.
operator BitmapId() const
Gets the id of this Bitmap.
boolcache(BitmapId id)
Cache this Bitmap into unused RAM in the bitmap cache.
boolcacheAll()
Cache all bitmaps from the Bitmap Database into RAM.
uint8_t *cacheGetAddress(BitmapId id)
Get address of cache buffer for this Bitmap.
boolcacheIsCached(BitmapId id)
Check if the Bitmap is cached.
boolcacheRemoveBitmap(BitmapId id)
Remove this Bitmap from the RAM cache.
boolcacheReplaceBitmap(BitmapId out, BitmapId in)
Replace a Bitmap in RAM with another Bitmap.
voidclearCache()
Clears the cached bitmaps from RAM.
voidcompactCache()
Compact the bitmap cache to get continuous free memory on top.
booldecompress(BitmapId id, uint16_t * buffer =0)
Decompress a compressed bitmap into the bitmap cache.
booldynamicBitmapAddSolidRect(BitmapId id, const Rect & solidRect)
Updates the solid rectangle of a dynamic Bitmap to include the given rectangle.
BitmapIddynamicBitmapCreate(const uint16_t width, const uint16_t height, BitmapFormat format, ClutFormat clutFormat =CLUT_FORMAT_L8_ARGB8888)
Create a dynamic Bitmap.
BitmapIddynamicBitmapCreateCopy(const BitmapId id)
Create a dynamic Bitmap as a copy of an existing bitmap.
BitmapIddynamicBitmapCreateCustom(const uint16_t width, const uint16_t height, uint8_t customSubformat, uint32_t size)
Create a dynamic bitmap in custom format.
BitmapIddynamicBitmapCreateExternal(const uint16_t width, const uint16_t height, const void * pixels, BitmapFormat format, uint8_t customSubformat =0)
Create a dynamic bitmap without reserving memory in the dynamic bitmap cache.
BitmapIddynamicBitmapCreateL8(const uint16_t width, const uint16_t height, ClutFormat clutFormat, uint16_t clutSize =256)
Create a dynamic L8 Bitmap.
booldynamicBitmapDelete(BitmapId id)
Delete a dynamic bitmap.
voiddynamicBitmapFill(const BitmapId id, const colortype color, const uint8_t alpha =255)
Fill a dynamic Bitmap with a color.
voiddynamicBitmapFillRect(const BitmapId id, const Rect & rect, const colortype color, const uint8_t alpha =255)
Fill parts of a dynamic Bitmap with a color.
uint8_t *dynamicBitmapGetAddress(BitmapId id)
Get the address of the dynamic Bitmap data.
booldynamicBitmapSetSolidRect(BitmapId id, const Rect & solidRect)
Set the solid rectangle of a dynamic Bitmap.
uint8_t *getCacheTopAddress()
Gets the address of the first unused memory in the cache.
boolisDynamicBitmap(BitmapId id)
Check if a given bitmap id is the id of a dynamic bitmap.
voidregisterBitmapDatabase(const BitmapData data, const uint16_t n, uint16_t cachep =0, uint32_t csize =0, uint32_t numberOfDynamicBitmaps =0)
Registers an array of bitmaps.
voidremoveCache()
Removes the Bitmap cache.
voidsetCache(uint16_t * cachep, uint32_t csize, uint32_t numberOfDynamicBitmaps =0)
Register a memory region in which Bitmap data can be cached.

Public Types Documentation

BitmapFormat

Data of a bitmap can be stored in the following formats.

RGB56516-bit, 5 bits for red, 6 bits for green, 5 bits for blue. No alpha channel
RGB88824-bit, 8 bits for each of red, green and blue. No alpha channel
ARGB888832-bit, 8 bits for each of red, green, blue and alpha channel
BW1-bit, black / white. No alpha channel
BW_RLE1-bit, black / white. No alpha channel. Image is compressed with horizontal RLE
GRAY22-bit grayscale
GRAY44-bit grayscale
ARGB22228-bit color
ABGR22228-bit color
RGBA22228-bit color
BGRA22228-bit color
L88-bit indexed color
A44-bit alpha level
CUSTOMNon-standard platform specific format.

ClutFormat

Color data of a clut can be stored in the following formats.

CLUT_FORMAT_L8_ARGB888832-bit, 8 bits for each of red, green, blue and alpha
CLUT_FORMAT_L8_RGB88824-bit, 8 bits for each of red, green and blue. No per pixel alpha channel
CLUT_FORMAT_L8_RGB56516-bit, 5 bits for red, 6 bits for green, 5 bits for blue. No per pixel alpha channel

Compression

Algorithms used for L8 images compression can be stored in the following formats.

COMPRESSION_L8_NONENo compression applied on the L8 image.
COMPRESSION_L8_L4L4 compression applied on the L8 image.
COMPRESSION_L8_RLERLE compression applied on the L8 image.
COMPRESSION_L8_LZW9LZW9 compression applied on the L8 image.

Public Functions Documentation

Bitmap

Bitmap(const BitmapIdid =BITMAP_INVALID)

Creates and binds a Bitmap instance to the corresponding entry in the BitmapData array.

Parameters:
id(Optional) The unique bitmap identifier.

getData

const uint8_t * getData()const

Gets a pointer to the Bitmap data.

Returns:

A pointer to the raw Bitmap data.

Note

If this Bitmap is cached, it will return the cached version of Bitmap data.

getExtraData

const uint8_t * getExtraData()const

Gets a pointer to the extra (alpha) data, if present in the Bitmap.

For images stored in L8 format, a pointer to the CLUT will be returned. For non-opaque RGB565 images, a pointer to the alpha channel will be returned.

Returns:

A pointer to the raw alpha channel data or CLUT. If no alpha channel or CLUT exist for the given Bitmap, 0 is returned.

Note

If this Bitmap is cached, it will return the cached version of alpha data for this Bitmap.

getFormat

BitmapFormat getFormat()const

Gets the format of how the Bitmap is stored.

Returns:

The format of how the Bitmap data is stored.

getHeight

int16_t getHeight()const

Gets the height of the Bitmap in pixels.

Returns:

The Bitmap height in pixels.

getId

BitmapId getId()const

Gets the id of this Bitmap.

Returns:

The id of this Bitmap.

getRect

Rect getRect()const

Gets the rectangle describing the dimensions of the Bitmap.

Returns:

a Rect describing the dimensions of this Bitmap.

getSolidRect

Rect getSolidRect()const

Gets the largest solid, i.e.

not transparent, rectangle in the Bitmap.

Returns:

The maximum solid rectangle of the Bitmap.

getWidth

int16_t getWidth()const

Gets the width of the Bitmap in pixels.

Returns:

The Bitmap width in pixels.

hasTransparentPixels

Query if this object has transparent pixels.

Returns:

True if this bitmap has transparent pixels.

isAlphaPerPixel

bool isAlphaPerPixel()const

Query if this object has an alpha channel.

Returns:

True if the bitmap contains an alpha channel (an alpha value for each pixel)

operator BitmapId

Gets the id of this Bitmap.

Returns:

The id of this Bitmap.

cache

static bool cache(BitmapIdid)

Cache this Bitmap into unused RAM in the bitmap cache.

A memory region large enough to hold this bitmap must be configured and a large enough part of it must be available. Caching of a bitmap may involve a defragmentation of the bitmap cache.

Parameters:
idThe id of the Bitmap to cache.
Returns:

true if caching went well, false otherwise.

See also:

cacheAll

static bool cacheAll()

Cache all bitmaps from the Bitmap Database into RAM.

A memory region large enough to hold all bitmaps must be configured.

Returns:

True if all bitmaps where cached.

See also:

cacheGetAddress

static uint8_t * cacheGetAddress(BitmapIdid)

Get address of cache buffer for this Bitmap.

Parameters:
idThe id of the Bitmap in cache.
Returns:

Address if Bitmap was found, zero otherwise.

Note

The address is only valid until next Bitmap::cache() call.

cacheIsCached

static bool cacheIsCached(BitmapIdid)

Check if the Bitmap is cached.

Parameters:
idThe id of the Bitmap.
Returns:

true if Bitmap is cached.

cacheRemoveBitmap

static bool cacheRemoveBitmap(BitmapIdid)

Remove this Bitmap from the RAM cache.

Unless the Bitmap is otherwise stored in (slower) memory it can not be drawn anymore and must be cached again before use. The RAM freed can be used for caching of another bitmap.

Parameters:
idThe id of the Bitmap to cache.
Returns:

true if Bitmap was found and removed, false otherwise.

See also:

cacheReplaceBitmap

static bool cacheReplaceBitmap(BitmapIdout ,
BitmapIdin
)

Replace a Bitmap in RAM with another Bitmap.

The Bitmaps must have same size.

Parameters:
outThe id of the Bitmap to remove from the cache.
inThe id of the Bitmap to cache.
Returns:

true if the replacement went well, false otherwise.

clearCache

static void clearCache()

Clears the cached bitmaps from RAM.

compactCache

static void compactCache()

Compact the bitmap cache to get continuous free memory on top.

This method is called by Bitmap::cache when required.

decompress

static bool decompress(BitmapIdid ,
uint16_t *buffer =0
)

Decompress a compressed bitmap into the bitmap cache.

The decompressed bitmap will automatically be used by all Widgets.

Only compressed L8 images can be decompressed. The decompressed bitmap will be L8 with an unchanged palette.

When decompressing L8 bitmaps compressed with LZW an array of size 2048 bytes (16 bit aligned) must be supplied. The array is only used during decompressing.

Parameters:
idThe id of the Bitmap to decompress.
bufferPointer to a buffer for LZW decompression.
Returns:

true if the bitmap was decompressed.

dynamicBitmapAddSolidRect

static bool dynamicBitmapAddSolidRect(BitmapIdid ,
const Rect &solidRect
)

Updates the solid rectangle of a dynamic Bitmap to include the given rectangle.

Only relevant for ARGB8888 bitmap and 8bpp bitmap formats, as these formats include an alpha channel. The solid part of the Bitmap is drawn faster than the transparent parts.

Parameters:
idThe identifier.
solidRectThe solid rectangle.
Returns:

true if it succeeds, false if it fails.

dynamicBitmapCreate

static BitmapId dynamicBitmapCreate(const uint16_twidth ,
const uint16_theight ,
BitmapFormatformat ,
ClutFormatclutFormat =CLUT_FORMAT_L8_ARGB8888
)

Create a dynamic Bitmap.

The clutFormat parameter is ignored for bitmaps not in L8 format (consider using dynamicBitmapCreateL8 instead). Creation of a new dynamic bitmap may cause existing dynamic bitmaps to be moved in memory. Do not rely on bitmap memory addresses of dynamic bitmaps obtained from dynamicBitmapGetAddress() to be valid across calls to dynamicBitmapCreate().

Parameters:
widthWidth of the Bitmap.
heightHeight of the Bitmap.
formatBitmap format of the Bitmap.
clutFormat(Optional) Color LookUp Table format of the Bitmap (only used if format is Bitmap::L8).
Returns:

BitmapId of the new Bitmap or BITMAP_INVALID if cache memory is full.

See also:

dynamicBitmapCreateCopy

static BitmapId dynamicBitmapCreateCopy(const BitmapIdid)

Create a dynamic Bitmap as a copy of an existing bitmap.

Parameters:
idThe ID of the bitmap to copy.
Returns:

BitmapId of the new Bitmap or BITMAP_INVALID if cache memory is full.

See also:

dynamicBitmapCreateCustom

static BitmapId dynamicBitmapCreateCustom(const uint16_twidth ,
const uint16_theight ,
uint8_tcustomSubformat ,
uint32_tsize
)

Create a dynamic bitmap in custom format.

size number of bytes is reserved in the dynamic bitmap cache. A more specific format can be given in the customSubformat parameter for use when handling more than one CUSTOM format. Set the solid rect if applicable.

Parameters:
widthWidth of the bitmap.
heightHeight of the bitmap.
customSubformatCustom format specifier
sizeSize in bytes of the dynamic bitmap
Returns:

BitmapId of the new bitmap or BITMAP_INVALID if cache memory is full.

Note

Creation of a new dynamic bitmap may cause existing dynamic bitmaps to be moved in memory. Do not rely on bitmap memory addresses of dynamic bitmaps obtained from dynamicBitmapGetAddress() to be valid across calls to dynamicBitmapCreateCustom() .

See also:

dynamicBitmapCreateExternal

static BitmapId dynamicBitmapCreateExternal(const uint16_twidth ,
const uint16_theight ,
const void *pixels ,
BitmapFormatformat ,
uint8_tcustomSubformat =0
)

Create a dynamic bitmap without reserving memory in the dynamic bitmap cache.

The pixels must be already available in the memory, e.g. in flash. No copying is performed.

Parameters:
widthWidth of the bitmap.
heightHeight of the bitmap.
pixelsPointer to the bitmap pixels.
formatBitmap format of the bitmap.
customSubformatCustom format specifier
Returns:

BitmapId of the new bitmap or BITMAP_INVALID if not possible.

See also:

dynamicBitmapCreateL8

static BitmapId dynamicBitmapCreateL8(const uint16_twidth ,
const uint16_theight ,
ClutFormatclutFormat ,
uint16_tclutSize =256
)

Create a dynamic L8 Bitmap.

Creation of a new dynamic bitmap may cause existing dynamic bitmaps to be moved in memory. Do not rely on bitmap memory addresses of dynamic bitmaps obtained from dynamicBitmapGetAddress() to be valid across calls to dynamicBitmapCreate().

Parameters:
widthWidth of the Bitmap.
heightHeight of the Bitmap.
clutFormatColor LookUp Table format of the L8 Bitmap.
clutSize(Optional) Color LookUp Table palette size (default=256).
Returns:

BitmapId of the new Bitmap or BITMAP_INVALID if cache memory is full.

See also:

dynamicBitmapDelete

static bool dynamicBitmapDelete(BitmapIdid)

Delete a dynamic bitmap.

Parameters:
idThe BitmapId of the dynamic Bitmap.
Returns:

true if it succeeds, false if it fails.

dynamicBitmapFill

static void dynamicBitmapFill(const BitmapIdid ,
const colortypecolor ,
const uint8_talpha =255
)

Fill a dynamic Bitmap with a color.

If alpha is less than 255, the color will be blended onto the existing data in the dynamic bitmap.

Parameters:
idThe ID of the dynamic bitmap to fill.
colorThe color.
alpha(Optional) The alpha (default is 255, i.e. solid).
See also:

dynamicBitmapFillRect

static void dynamicBitmapFillRect(const BitmapIdid ,
const Rect &rect ,
const colortypecolor ,
const uint8_talpha =255
)

Fill parts of a dynamic Bitmap with a color.

If alpha is less than 255, the color will be blended onto the existing data in the dynamic bitmap.

Parameters:
idThe ID of the dynamic bitmap to fill.
rectThe rectangle to fill.
colorThe color.
alpha(Optional) The alpha (default is 255, i.e. solid).
See also:

dynamicBitmapGetAddress

static uint8_t * dynamicBitmapGetAddress(BitmapIdid)

Get the address of the dynamic Bitmap data.

It is important that the address of a dynamic Bitmap is not stored elsewhere as a dynamic Bitmap may be moved in memory when other bitmaps are added and removed. Only store the BitmapId and ask for the address of the Bitmap data when needed. The address of a dynamic bitmap may change when other dynamic bitmaps are added and removed.

Parameters:
idThe BitmapId of the dynamic bitmap.
Returns:

null if it fails, else an uint8_t*.

Note

Never keep the address of dynamic images, only store the BitmapId as that will not change.

dynamicBitmapSetSolidRect

static bool dynamicBitmapSetSolidRect(BitmapIdid ,
const Rect &solidRect
)

Set the solid rectangle of a dynamic Bitmap.

Only relevant for ARGB8888 Bitmap and 8bpp Bitmap formats, as these formats include an alpha channel. The solid part of the Bitmap is drawn faster than the transparent parts.

Parameters:
idThe identifier.
solidRectThe solid rectangle.
Returns:

true if it succeeds, false if it fails.

getCacheTopAddress

static uint8_t * getCacheTopAddress()

Gets the address of the first unused memory in the cache.

Can be used in advanced application to reduce power consumption of external RAM by turning off unused RAM.

Returns:

Returns the highest used address in the cache.

isDynamicBitmap

static bool isDynamicBitmap(BitmapIdid)

Check if a given bitmap id is the id of a dynamic bitmap.

Parameters:
idThe BitmapId of the dynamic Bitmap.
Returns:

true if the bitmap is dynamic, false otherwise.

registerBitmapDatabase

static void registerBitmapDatabase(const BitmapData *data ,
const uint16_tn ,
uint16_t *cachep =0,
uint32_tcsize =0,
uint32_tnumberOfDynamicBitmaps =0
)

Registers an array of bitmaps.

All Bitmap instances are bound to this database. This function is called automatically from HAL::touchgfx_generic_init().

Parameters:
dataA reference to the BitmapData storage array.
nThe number of bitmaps in the array.
cachep(Optional) Pointer to memory region in which bitmap data can be cached.
csize(Optional) Size of cache memory region in bytes (0 if unused)
numberOfDynamicBitmaps(Optional) Number of dynamic bitmaps to be allowed in the cache.

removeCache

static void removeCache()

Removes the Bitmap cache.

The memory can hereafter be used for other purposes. All dynamic Bitmap IDs are invalid after this.

setCache

static void setCache(uint16_t *cachep ,
uint32_tcsize ,
uint32_tnumberOfDynamicBitmaps =0
)

Register a memory region in which Bitmap data can be cached.

Parameters:
cachepPointer to memory region in which bitmap data can be cached.
csizeSize of cache memory region in bytes.
numberOfDynamicBitmaps(Optional) Number of dynamic bitmaps to be allowed in the cache.