Skip to main content
Version: 4.16

Bitmap

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.

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.
uint16_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.
uint16_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.
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.
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.
booldynamicBitmapDelete(BitmapId id)
Delete a dynamic bitmap.
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

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#

uint16_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#

uint16_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.

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. 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.
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.

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.

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:

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.

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.