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
Creates and binds a Bitmap instance to the corresponding entry in the BitmapData array.
id | (Optional) The unique bitmap identifier. |
getData
const uint8_t * getData | ( | ) | const |
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.
A pointer to the raw alpha channel data or CLUT. If no alpha channel or CLUT exist for the given Bitmap, 0 is returned.
getFormat
BitmapFormat getFormat | ( | ) | const |
getHeight
int16_t getHeight | ( | ) | const |
getId
getRect
Rect getRect | ( | ) | const |
getSolidRect
Rect getSolidRect | ( | ) | const |
getWidth
hasTransparentPixels
bool hasTransparentPixels | ( | ) | const |
Query if this object has transparent pixels.
True if this bitmap has transparent pixels.
isAlphaPerPixel
bool isAlphaPerPixel | ( | ) | const |
Query if this object has an alpha channel.
True if the bitmap contains an alpha channel (an alpha value for each pixel)
operator BitmapId
operator BitmapId | ( | ) | const |
cache
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.
id | The id of the Bitmap to cache. |
true if caching went well, false otherwise.
cacheAll
static bool cacheAll | ( | ) |
cacheGetAddress
static uint8_t * cacheGetAddress | ( | BitmapId | id | ) | |
Get address of cache buffer for this Bitmap.
id | The id of the Bitmap in cache. |
Address if Bitmap was found, zero otherwise.
Note
The address is only valid until next Bitmap::cache() call.
cacheIsCached
static bool cacheIsCached | ( | BitmapId | id | ) | |
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.
id | The id of the Bitmap to cache. |
true if Bitmap was found and removed, false otherwise.
cacheReplaceBitmap
static bool cacheReplaceBitmap | ( | BitmapId | out , | ||
BitmapId | in | ||||
) |
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.
id | The id of the Bitmap to decompress. |
buffer | Pointer to a buffer for LZW decompression. |
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.
id | The id of the Bitmap to decompress. |
buffer | Pointer to a buffer for LZW decompression. |
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.
id | The id of the Bitmap to decompress. |
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.
id | The identifier. |
solidRect | The solid rectangle. |
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().
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). |
BitmapId of the new Bitmap or BITMAP_INVALID if cache memory is full.
dynamicBitmapCreateCopy
static BitmapId dynamicBitmapCreateCopy | ( | const BitmapId | id | ) | |
Create a dynamic Bitmap as a copy of an existing bitmap.
id | The ID of the bitmap to copy. |
BitmapId of the new Bitmap or BITMAP_INVALID if cache memory is full.
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.
width | Width of the bitmap. |
height | Height of the bitmap. |
customSubformat | Custom format specifier |
size | Size in bytes of the dynamic bitmap |
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() .
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.
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 |
BitmapId of the new bitmap or BITMAP_INVALID if not possible.
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().
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). |
BitmapId of the new Bitmap or BITMAP_INVALID if cache memory is full.
dynamicBitmapDelete
static bool dynamicBitmapDelete | ( | BitmapId | id | ) | |
Delete a dynamic bitmap.
id | The BitmapId of the dynamic Bitmap. |
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.
id | The ID of the dynamic bitmap to fill. |
color | The color. |
alpha | (Optional) The alpha (default is 255, i.e. solid). |
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.
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). |
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.
id | The BitmapId of the dynamic bitmap. |
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.
id | The identifier. |
solidRect | The solid rectangle. |
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 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.
id | The BitmapId of the dynamic Bitmap. |
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().
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 | ( | ) |
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.
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. |