Detailed Description

Sub-Module for image handling.

Data Structures
struct	gImage
	The structure for an image. More...

Functions
void	gdispImageInit (gImage *img)
	Initialise a gImage object. More...

gdispImageError	gdispImageOpenGFile (gImage img, GFILE f)
	Open an image using an open GFILE and get it ready for drawing. More...

void	gdispImageClose (gImage *img)
	Close an image and release any dynamically allocated working storage. More...

gBool	gdispImageIsOpen (gImage *img)
	Is an image open. More...

void	gdispImageSetBgColor (gImage *img, gColor bgcolor)
	Set the background color of the image. More...

gdispImageError	gdispImageCache (gImage *img)
	Cache the image. More...

gdispImageError	gdispGImageDraw (GDisplay g, gImage img, gCoord x, gCoord y, gCoord cx, gCoord cy, gCoord sx, gCoord sy)
	Draw the image. More...

gDelay	gdispImageNext (gImage *img)
	Prepare for the next frame/page in the image file. More...

gU16	gdispImageGetPaletteSize (gImage *img)
	Get the number of entries in the color palette. More...

gColor	gdispImageGetPalette (gImage *img, gU16 index)
	Get an entry in the color palette. More...

gBool	gdispImageAdjustPalette (gImage *img, gU16 index, gColor newColor)
	Modify an entry in the color palette. More...

Macros
#define	gdispImageOpenFile(img, filename) gdispImageOpenGFile((img), gfileOpen((filename), "rb"))
	Open an image in a file and get it ready for drawing. More...

#define	gdispImageOpenBaseFileStream(img, BaseFileStreamPtr) gdispImageOpenGFile((img), gfileOpenBaseFileStream((BaseFileStreamPtr), "rb"))
	Open an image in a ChibiOS basefilestream and get it ready for drawing. More...

#define	gdispImageOpenMemory(img, ptr) gdispImageOpenGFile((img), gfileOpenMemory((void *)(ptr), "rb"))
	Open an image in memory and get it ready for drawing. More...

Typedefs
typedef gU16	gdispImageType
	The type of image. More...

typedef gU16	gdispImageError
	An image error code. More...

typedef gU16	gdispImageFlags
	Image flags. More...

typedef struct gImage	gImage
	The structure for an image. More...

Function Documentation

◆ gdispGImageDraw()

gdispImageError gdispGImageDraw	(	GDisplay *	g,
		gImage *	img,
		gCoord	x,
		gCoord	y,
		gCoord	cx,
		gCoord	cy,
		gCoord	sx,
		gCoord	sy
	)

Draw the image.

Returns: GDISP_IMAGE_ERR_OK (0) on success or an error code.

Parameters

[in]	g	The display to draw on
[in]	img	The image structure
[in]	x,y	The screen location to draw the image
[in]	cx,cy	The area on the screen to draw
[in]	sx,sy	The image position to start drawing at

Precondition: gdispImageOpen() must have returned successfully.

Note: If sx,sy + cx,cy is outside the image boundaries the area outside the image is simply not drawn.; If gdispImageCache() has been called first for this frame, this routine will draw using a fast blit from the cached frame. If not, it reads the input and decodes it as it is drawing. This may be significantly slower than if the image has been cached (but uses a lot less RAM)

◆ gdispImageAdjustPalette()

gBool gdispImageAdjustPalette	(	gImage *	img,
		gU16	index,
		gColor	newColor
	)

Modify an entry in the color palette.

Returns: gTrue on success, gFalse otherwise.

Parameters

[in]	img	The image structure
[in]	index	The index of the color palette entry
[in]	newColor	The new color value of the specified entry

Precondition: gdispImageOpen() must have returned successfully.

Note: This function will return gFalse if the index is out of bounds or if the image doesn't use a color palette.

◆ gdispImageCache()

gdispImageError gdispImageCache ( gImage * img )

Cache the image.

Decodes and caches the current frame into RAM.

Returns: GDISP_IMAGE_ERR_OK (0) on success or an error code.

Parameters

[in] img The image structure

Precondition: gdispImageOpen() must have returned successfully.

Note: This can use a LOT of RAM!; The decoder may choose to ignore the request for caching. If it does so it will return GDISP_IMAGE_ERR_UNSUPPORTED_OK.; A fatal error here does not necessarily mean that drawing the image will fail. For example, a GDISP_IMAGE_ERR_NOMEMORY error simply means there isn't enough RAM to cache the image.

◆ gdispImageClose()

void gdispImageClose ( gImage * img )

Close an image and release any dynamically allocated working storage.

Parameters

[in] img The image structure

Precondition: gdispImageOpenFile() must have returned successfully.

Note: Also calls the IO close function (if it hasn't already been called).

◆ gdispImageGetPalette()

gColor gdispImageGetPalette	(	gImage *	img,
		gU16	index
	)

Get an entry in the color palette.

Returns: The color value at a given position in the color palette.

Parameters

[in]	img	The image structure
[in]	index	The index of the color palette entry

Precondition: gdispImageOpen() must have returned successfully.

Note: This function will return 0 if the index is out of bounds or if the image doesn't use a color palette.

◆ gdispImageGetPaletteSize()

gU16 gdispImageGetPaletteSize ( gImage * img )

Get the number of entries in the color palette.

Returns: The number of entries in the color palette or 0 if the image doesn't use a color palette.

Parameters

[in] img The image structure

Precondition: gdispImageOpen() must have returned successfully.

◆ gdispImageInit()

void gdispImageInit ( gImage * img )

Initialise a gImage object.

Parameters

[in] img The image structure to initialise

◆ gdispImageIsOpen()

gBool gdispImageIsOpen ( gImage * img )

Is an image open.

Returns: gTrue if the image is currently open.

Parameters

[in] img The image structure

Note: Be careful with calling this on an uninitialized image structure as the image will contain random data which may be interpreted as meaning the image is open. Clearing the Image structure to 0's will guarantee the image is seen as being closed.

◆ gdispImageNext()

gDelay gdispImageNext ( gImage * img )

Prepare for the next frame/page in the image file.

Returns: A time in milliseconds to keep displaying the current frame before trying to draw the next frame. Watch out for the special values gDelayNone and gDelayForever.

Parameters

[in] img The image structure

Precondition: gdispImageOpen() must have returned successfully.

Note: It will return gDelayNone if the first frame/page hasn't been drawn or if the next frame should be drawn immediately.; It will return gDelayForever if another image frame doesn't exist or an error has occurred.; Images that support multiple pages (eg TIFF files) will return gDelayNone between pages and then gDelayForever when there are no more pages.; An image that displays a looped animation will never return gDelayForever unless it gets an error.; Calling gdispImageDraw() after getting a gDelayForever will go back to drawing the first frame/page.

◆ gdispImageOpenGFile()

gdispImageError gdispImageOpenGFile	(	gImage *	img,
		GFILE *	f
	)

Open an image using an open GFILE and get it ready for drawing.

Determine the image format and get ready to decode the first image frame

Returns: GDISP_IMAGE_ERR_OK (0) on success or an error code.

Parameters

[in]	img	The image structure
[in]	f	The open GFILE stream.

Precondition: The GFILE must be open for reading.

Note: This determines which decoder to use and then initialises all other fields in the gImage structure.; The image background color is set to White.; There are three types of return - everything OK, partial success and unrecoverable failures. For everything OK it returns GDISP_IMAGE_ERR_OK. A partial success can be distinguished from a unrecoverable failure by testing the GDISP_IMAGE_ERR_UNRECOVERABLE bit in the error code. A partial success return code means an image can still be drawn but perhaps with reduced functionality eg only the first page of a multi-page image.; gdispImageClose() should be called when finished with the image. This will close the image and its underlying GFILE file. Note that images opened with partial success (eg GDISP_IMAGE_ERR_UNSUPPORTED_OK) still need to be closed when you are finished with them.

◆ gdispImageSetBgColor()

void gdispImageSetBgColor	(	gImage *	img,
		gColor	bgcolor
	)

Set the background color of the image.

Parameters

[in]	img	The image structure
[in]	bgcolor	The background color to use

Precondition: gdispImageOpen() must have returned successfully.

Note: This color is only used when an image has to restore part of the background before continuing with drawing that includes transparency eg some GIF animations.

Macro Definition Documentation

◆ gdispImageOpenBaseFileStream

#define gdispImageOpenBaseFileStream	(	img,
		BaseFileStreamPtr
	)	gdispImageOpenGFile((img), gfileOpenBaseFileStream((BaseFileStreamPtr), "rb"))

Open an image in a ChibiOS basefilestream and get it ready for drawing.

Determine the image format and get ready to decode the first image frame

Returns: GDISP_IMAGE_ERR_OK (0) on success or an error code.

Precondition: GFILE_NEED_CHIBIOSFS and GFX_USE_OS_CHIBIOS must be GFXON. This only makes sense on the ChibiOS operating system.

Parameters

[in]	img	The image structure
[in]	BaseFileStreamPtr	A pointer to an open BaseFileStream

Note: This function just opens the GFILE using the basefilestream and passes it to gdispImageOpenGFile().

Definition at line 134 of file gdisp_image.h.

◆ gdispImageOpenFile

#define gdispImageOpenFile	(	img,
		filename
	)	gdispImageOpenGFile((img), gfileOpen((filename), "rb"))

Open an image in a file and get it ready for drawing.

Determine the image format and get ready to decode the first image frame

Returns: GDISP_IMAGE_ERR_OK (0) on success or an error code.

Precondition: You must have included the file-system support into GFILE that you want to use.

Parameters

[in]	img	The image structure
[in]	filename	The filename to open

Note: This function just opens the GFILE using the filename and passes it to gdispImageOpenGFile().

Definition at line 119 of file gdisp_image.h.

◆ gdispImageOpenMemory

#define gdispImageOpenMemory	(	img,
		ptr
	)	gdispImageOpenGFile((img), gfileOpenMemory((void *)(ptr), "rb"))

Open an image in memory and get it ready for drawing.

Determine the image format and get ready to decode the first image frame

Returns: GDISP_IMAGE_ERR_OK (0) on success or an error code.

Precondition: GFILE_NEED_MEMFS must be GFXON

Parameters

[in]	img	The image structure
[in]	ptr	A pointer to the image bytes in memory

Note: This function just opens the GFILE using the basefilestream and passes it to gdispImageOpenGFile().

Definition at line 148 of file gdisp_image.h.

Typedef Documentation

◆ gdispImageError

typedef gU16 gdispImageError

An image error code.

Definition at line 37 of file gdisp_image.h.

◆ gdispImageFlags

typedef gU16 gdispImageFlags

Image flags.

Definition at line 51 of file gdisp_image.h.

◆ gdispImageType

typedef gU16 gdispImageType

The type of image.

Definition at line 26 of file gdisp_image.h.

◆ gImage

typedef struct gImage gImage

The structure for an image.

Detailed Description

Data Structures

Functions

Macros

Typedefs

Function Documentation

◆ gdispGImageDraw()

◆ gdispImageAdjustPalette()

◆ gdispImageCache()

◆ gdispImageClose()

◆ gdispImageGetPalette()

◆ gdispImageGetPaletteSize()

◆ gdispImageInit()

◆ gdispImageIsOpen()

◆ gdispImageNext()

◆ gdispImageOpenGFile()

◆ gdispImageSetBgColor()

Macro Definition Documentation

◆ gdispImageOpenBaseFileStream

◆ gdispImageOpenFile

◆ gdispImageOpenMemory

Typedef Documentation

◆ gdispImageError

◆ gdispImageFlags

◆ gdispImageType

◆ gImage