Images

The GDISP module comes with a built-in image decoder. The decoder allows it to open an image of various formats and display it. As the GFILE module is being used internally, the image can be stored in different sources such as the internal flash or external memory like an SD card.

Before you continue to read this documentation, please consider to use the image box widget instead of the GIDSP image handling. It's much simpler to use.

Image formats

µGFX does currently come with the following image decoders:

Format	Description
BMP	Including BMP1, BMP4, BMP4_RLE, BMP8, BMP8_RLE, BMP16, BMP24, BMP32
GIF	Including transparency and multi-frame support (animations)
NATIVE	Uses the display drivers native format. See below.

We plan to add decoders for PNG and JPG images in the future.

NATIVE image format

The native image format consists of an 8 byte header followed by an array of bytes in the format your display controller accepts. Whilst hardware dependant, this format displays extremely quickly and with the least amount of RAM usage. It is ideal for images stored in FLASH. The header is:

{ 'N', 'I', width.hi, width.lo, height.hi, height.lo, format.hi, format.lo }

Where the format word is equal to GDISP_PIXELFORMAT which is defined in the configuration.h file of your GDISP driver.

RAM Usage

Image decoders use RAM to decode and display images. Whilst the image handlers have been written to use as little RAM as possible, for small micros with limited RAM the image formats used should be examined carefully. The image handlers do not allocate RAM to store the decompressed bitmaps (unlike most other image decoders), instead decoding the image again if it needs to be displayed. The only RAM used therefore is:

Some RAM to hold information on the image itself - typically 200-300 bytes. This RAM is maintained whilst the image is open. It may vary slightly for some images with some image formats (due to holding palettes etc). RAM allocated during the decoding process and freed once the decoding is done. The GIF image format requires around 12K of RAM to decode an image. BMP and NATIVE images do not require any extra RAM for decoding. If you decide to cache the image then RAM is required for the full decoded image. This should not be considered for low memory micros. For example, caching a 320x240 image on a 2 bytes per pixel display will take 150K of RAM (plus the normal decoding RAM). Stack space. You may need to increase your available stack space if you get exceptions when trying to decode images. Some image formats require a few hundred bytes of stack space to decode an image. Our image decoders have been written from the ground up to keep the image decoders as lean and mean as possible. Our current decoders use significantly less than other decoding libraries available. You can also test the RAM usage for your image formats and your particular images by setting GDISP_NEED_IMAGE_ACCOUNTING to TRUE in your gfxconf.h file. This adds two members to the image structure "memused" and "maxmemused" which can be examined to see exactly how much RAM decoding an image takes.

Caching

It's possible to use the gdispImageCache() to cache a decoded image into your RAM. When you don't cache an image, it will always be read again from flash, decoded and then displayed. When you cache your image, you just have to load it from RAM and display it. This is way faster, especially for PNG, JPG and GIF formants, since these require quite complex decoding algorithms. Note however that caching an image requires A LOT of RAM. Especially when you're using multi-frame GIF images or large image sizes.

If you cache your image, you still have to open() the image before you can draw it. When close() is called, it will free all memory used by the decoder including any cached images.

Calling the caching routine doesn't guarantee that your image will be cached. For example, if you don't have enough RAM, the image won't be cached. Since caching is fully optional, the image will still be drawn when you call the drawing routine. It will simply be decoded again.

A word about close()

The gdispImageClose() function is a complete cleanup. Call this routine will not only clean up all memory used by the decoder and the chaching, it will also close the filesystem. Therefore, this should really just be called when you're done with the image and you won't re-draw it for a longer time period.

Examples

The following code pieces show how to use the GDISP image decoder correctly. Please refer to the GFILE article to learn how to use the ROMFS.

#include "gfx.h"
 
/**
 * The image file must be stored on a GFILE file-system.
 * Use either GFILE_NEED_NATIVEFS or GFILE_NEED_ROMFS (or both).
 *
 * The ROMFS uses the file "romfs_files.h" to describe the set of files in the ROMFS.
 */
 
static gdispImage myImage;
 
int main(void) {
	coord_t			swidth, sheight;
 
	// Initialize uGFX and the underlying system
	gfxInit();
 
	// Get the display dimensions
	swidth = gdispGetWidth();
	sheight = gdispGetHeight();
 
	// Set up IO for our image
	gdispImageOpenFile(&myImage, "myImage.bmp");
	gdispImageDraw(&myImage, 0, 0, swidth, sheight, 0, 0);
	gdispImageClose(&myImage);
 
	while(1) {
		gfxSleepMilliseconds(1000);
	}
 
	return 0;
}