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

struct	BitmapData
	Data of a bitmap.
struct	CacheTableEntry
	Cache bookkeeping.
struct	DynamicBitmapData
	Data of a dynamic Bitmap.

Public Types

enum	BitmapFormat { RGB565, RGB888, ARGB8888, BW, BW_RLE, GRAY2, GRAY4, ARGB2222, ABGR2222, RGBA2222, BGRA2222, L8, A4, CUSTOM, COMPRESSED_RGB565, COMPRESSED_RGB888, COMPRESSED_ARGB8888 }
	Data of a bitmap can be stored in the following formats.
enum	ClutFormat { CLUT_FORMAT_L8_ARGB8888, CLUT_FORMAT_L8_RGB888, CLUT_FORMAT_L8_RGB565 }
	Color data of a clut can be stored in the following formats.
enum	Compression { 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.
BitmapFormat	getFormat() const
	Gets the format of how the Bitmap is stored.
int16_t	getHeight() const
	Gets the height of the Bitmap in pixels.
BitmapId	getId() const
	Gets the id of this Bitmap.
Rect	getRect() const
	Gets the rectangle describing the dimensions of the Bitmap.
Rect	getSolidRect() const
	Gets the largest solid, i.e.
int16_t	getWidth() const
	Gets the width of the Bitmap in pixels.
bool	hasTransparentPixels() const
	Query if this object has transparent pixels.
bool	isAlphaPerPixel() const
	Query if this object has an alpha channel.
	operator BitmapId() const
	Gets the id of this Bitmap.
bool	cache(BitmapId id)
	Cache this Bitmap into unused RAM in the bitmap cache.
bool	cacheAll()
	Cache all bitmaps from the Bitmap Database into RAM.
uint8_t *	cacheGetAddress(BitmapId id)
	Get address of cache buffer for this Bitmap.
bool	cacheIsCached(BitmapId id)
	Check if the Bitmap is cached.
bool	cacheRemoveBitmap(BitmapId id)
	Remove this Bitmap from the RAM cache.
bool	cacheReplaceBitmap(BitmapId out, BitmapId in)
	Replace a Bitmap in RAM with another Bitmap.
void	clearCache()
	Clears the cached bitmaps from RAM.
void	compactCache()
	Compact the bitmap cache to get continuous free memory on top.
bool	decompress(BitmapId id, uint16_t * buffer =0)
	Decompress a compressed bitmap into the bitmap cache.
bool	decompressL8(BitmapId id, uint16_t * buffer =0)
	Decompress a compressed bitmap into the bitmap cache.
bool	decompressRGB(BitmapId id)
	Decompress a compressed bitmap into the bitmap cache.
bool	dynamicBitmapAddSolidRect(BitmapId id, const Rect & solidRect)
	Updates the solid rectangle of a dynamic Bitmap to include the given rectangle.
BitmapId	dynamicBitmapCreate(const uint16_t width, const uint16_t height, BitmapFormat format, ClutFormat clutFormat =CLUT_FORMAT_L8_ARGB8888)
	Create a dynamic Bitmap.
BitmapId	dynamicBitmapCreateCopy(const BitmapId id)
	Create a dynamic Bitmap as a copy of an existing bitmap.
BitmapId	dynamicBitmapCreateCustom(const uint16_t width, const uint16_t height, uint8_t customSubformat, uint32_t size)
	Create a dynamic bitmap in custom format.
BitmapId	dynamicBitmapCreateExternal(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.
BitmapId	dynamicBitmapCreateL8(const uint16_t width, const uint16_t height, ClutFormat clutFormat, uint16_t clutSize =256)
	Create a dynamic L8 Bitmap.
bool	dynamicBitmapDelete(BitmapId id)
	Delete a dynamic bitmap.
void	dynamicBitmapFill(const BitmapId id, const colortype color, const uint8_t alpha =255)
	Fill a dynamic Bitmap with a color.
void	dynamicBitmapFillRect(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.
bool	dynamicBitmapSetSolidRect(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.
bool	isDynamicBitmap(BitmapId id)
	Check if a given bitmap id is the id of a dynamic bitmap.
void	registerBitmapDatabase(const BitmapData data, const uint16_t n, uint16_t cachep =0, uint32_t csize =0, uint32_t numberOfDynamicBitmaps =0)
	Registers an array of bitmaps.
void	removeCache()
	Removes the Bitmap cache.
void	setCache(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

enum BitmapFormat

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

RGB565	16-bit, 5 bits for red, 6 bits for green, 5 bits for blue. No alpha channel
RGB888	24-bit, 8 bits for each of red, green and blue. No alpha channel
ARGB8888	32-bit, 8 bits for each of red, green, blue and alpha channel
BW	1-bit, black / white. No alpha channel
BW_RLE	1-bit, black / white. No alpha channel. Image is compressed with horizontal RLE
GRAY2	2-bit grayscale
GRAY4	4-bit grayscale
ARGB2222	8-bit color
ABGR2222	8-bit color
RGBA2222	8-bit color
BGRA2222	8-bit color
L8	8-bit indexed color
A4	4-bit alpha level
CUSTOM	Non-standard platform specific format.
COMPRESSED_RGB565	16-bit, 5 bits for red, 6 bits for green, 5 bits for blue. No alpha channel. Compressed with QOI algorithm.
COMPRESSED_RGB888	24-bit, 8 bits for each of red, green and blue. No alpha channel. Compressed with QOI algorithm.
COMPRESSED_ARGB8888	32-bit, 8 bits for each of red, green, blue and alpha channel. Compressed with QOI algorithm.

ClutFormat

enum ClutFormat

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

CLUT_FORMAT_L8_ARGB8888	32-bit, 8 bits for each of red, green, blue and alpha
CLUT_FORMAT_L8_RGB888	24-bit, 8 bits for each of red, green and blue. No per pixel alpha channel
CLUT_FORMAT_L8_RGB565	16-bit, 5 bits for red, 6 bits for green, 5 bits for blue. No per pixel alpha channel

Compression

enum Compression

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

COMPRESSION_L8_NONE	No compression applied on the L8 image.
COMPRESSION_L8_L4	L4 compression applied on the L8 image.
COMPRESSION_L8_RLE	RLE compression applied on the L8 image.
COMPRESSION_L8_LZW9	LZW9 compression applied on the L8 image.

Public Functions Documentation

Bitmap

Bitmap	(	const BitmapId	id =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

bool hasTransparentPixels	(			)	const

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

operator BitmapId	(			)	const

Gets the id of this Bitmap.

Returns:

The id of this Bitmap.

cache

static bool cache	(	BitmapId	id	)

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:

id	The id of the Bitmap to cache.

Returns:

true if caching went well, false otherwise.

See also:

registerBitmapDatabase, compactCache

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:

cache

cacheGetAddress

static uint8_t * cacheGetAddress	(	BitmapId	id	)

Get address of cache buffer for this Bitmap.

Parameters:

id	The 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	(	BitmapId	id	)

Check if the Bitmap is cached.

Parameters:

id	The id of the Bitmap.

Returns:

true if Bitmap is cached.

cacheRemoveBitmap

static bool cacheRemoveBitmap	(	BitmapId	id	)

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:

id	The id of the Bitmap to cache.

Returns:

true if Bitmap was found and removed, false otherwise.

See also:

registerBitmapDatabase

cacheReplaceBitmap

static bool cacheReplaceBitmap	(	BitmapId	out ,
		BitmapId	in
		)

Replace a Bitmap in RAM with another Bitmap.

The Bitmaps must have same size.

Parameters:

out	The id of the Bitmap to remove from the cache.
in	The 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	(	BitmapId	id ,
		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, RGB565, RGB888 and ARGB8888 bitmaps can be decompressed with this method.

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:

id	The id of the Bitmap to decompress.
buffer	Pointer to a buffer for LZW decompression.

Returns:

true if the bitmap was decompressed.

decompressL8

static bool decompressL8	(	BitmapId	id ,
		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 bitmaps can be decompressed with this method. 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:

id	The id of the Bitmap to decompress.
buffer	Pointer to a buffer for LZW decompression.

Returns:

true if the bitmap was decompressed.

decompressRGB

static bool decompressRGB	(	BitmapId	id	)

Decompress a compressed bitmap into the bitmap cache.

The decompressed bitmap will automatically be used by all Widgets.

Only compressed RGB565, RGB888 and ARGB8888 bitmaps can be decompressed with this method.

Parameters:

id	The id of the Bitmap to decompress.

Returns:

true if the bitmap was decompressed.

dynamicBitmapAddSolidRect

static bool dynamicBitmapAddSolidRect	(	BitmapId	id ,
		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:

id	The identifier.
solidRect	The solid rectangle.

Returns:

true if it succeeds, false if it fails.

dynamicBitmapCreate

static BitmapId dynamicBitmapCreate	(	const uint16_t	width ,
		const uint16_t	height ,
		BitmapFormat	format ,
		ClutFormat	clutFormat =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:

width	Width of the Bitmap.
height	Height of the Bitmap.
format	Bitmap 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:

DynamicBitmapData, dynamicBitmapCreateL8, dynamicBitmapCreateCopy

dynamicBitmapCreateCopy

static BitmapId dynamicBitmapCreateCopy	(	const BitmapId	id	)

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

Parameters:

id	The ID of the bitmap to copy.

Returns:

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

See also:

dynamicBitmapCreate

dynamicBitmapCreateCustom

static BitmapId dynamicBitmapCreateCustom	(	const uint16_t	width ,
		const uint16_t	height ,
		uint8_t	customSubformat ,
		uint32_t	size
		)

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:

width	Width of the bitmap.
height	Height of the bitmap.
customSubformat	Custom format specifier
size	Size 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:

dynamicBitmapGetAddress, dynamicBitmapCreate, dynamicBitmapSetSolidRect

dynamicBitmapCreateExternal

static BitmapId dynamicBitmapCreateExternal	(	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.

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

Parameters:

width	Width of the bitmap.
height	Height of the bitmap.
pixels	Pointer to the bitmap pixels.
format	Bitmap format of the bitmap.
customSubformat	Custom format specifier

Returns:

BitmapId of the new bitmap or BITMAP_INVALID if not possible.

See also:

dynamicBitmapGetAddress, dynamicBitmapCreate, dynamicBitmapSetSolidRect

dynamicBitmapCreateL8

static BitmapId dynamicBitmapCreateL8	(	const uint16_t	width ,
		const uint16_t	height ,
		ClutFormat	clutFormat ,
		uint16_t	clutSize =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:

width	Width of the Bitmap.
height	Height of the Bitmap.
clutFormat	Color 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:

DynamicBitmapData, dynamicBitmapCreate

dynamicBitmapDelete

static bool dynamicBitmapDelete	(	BitmapId	id	)

Delete a dynamic bitmap.

Parameters:

id	The BitmapId of the dynamic Bitmap.

Returns:

true if it succeeds, false if it fails.

dynamicBitmapFill

static void dynamicBitmapFill	(	const BitmapId	id ,
		const colortype	color ,
		const uint8_t	alpha =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:

id	The ID of the dynamic bitmap to fill.
color	The color.
alpha	(Optional) The alpha (default is 255, i.e. solid).

See also:

dynamicBitmapCreateCopy, dynamicBitmapFillRect

dynamicBitmapFillRect

static void dynamicBitmapFillRect	(	const BitmapId	id ,
		const Rect &	rect ,
		const colortype	color ,
		const uint8_t	alpha =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:

id	The ID of the dynamic bitmap to fill.
rect	The rectangle to fill.
color	The color.
alpha	(Optional) The alpha (default is 255, i.e. solid).

See also:

dynamicBitmapCreateCopy, dynamicBitmapFill

dynamicBitmapGetAddress

static uint8_t * dynamicBitmapGetAddress	(	BitmapId	id	)

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:

id	The 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	(	BitmapId	id ,
		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:

id	The identifier.
solidRect	The 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	(	BitmapId	id	)

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

Parameters:

id	The BitmapId of the dynamic Bitmap.

Returns:

true if the bitmap is dynamic, false otherwise.

registerBitmapDatabase

static void registerBitmapDatabase	(	const BitmapData *	data ,
		const uint16_t	n ,
		uint16_t *	cachep =0,
		uint32_t	csize =0,
		uint32_t	numberOfDynamicBitmaps =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:

data	A reference to the BitmapData storage array.
n	The 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_t	csize ,
		uint32_t	numberOfDynamicBitmaps =0
		)

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

Parameters:

cachep	Pointer to memory region in which bitmap data can be cached.
csize	Size of cache memory region in bytes.
numberOfDynamicBitmaps	(Optional) Number of dynamic bitmaps to be allowed in the cache.