version 2.8
Image

Detailed Description

Sub-Module for image handling.

Data Structures

struct  gdispImage
 The structure for an image. More...
 

Functions

void gdispImageInit (gdispImage *img)
 Initialise a gdispImage object. More...
 
gdispImageError gdispImageOpenGFile (gdispImage *img, GFILE *f)
 Open an image using an open GFILE and get it ready for drawing. More...
 
void gdispImageClose (gdispImage *img)
 Close an image and release any dynamically allocated working storage. More...
 
bool_t gdispImageIsOpen (gdispImage *img)
 Is an image open. More...
 
void gdispImageSetBgColor (gdispImage *img, color_t bgcolor)
 Set the background color of the image. More...
 
gdispImageError gdispImageCache (gdispImage *img)
 Cache the image. More...
 
gdispImageError gdispGImageDraw (GDisplay *g, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy)
 Draw the image. More...
 
delaytime_t gdispImageNext (gdispImage *img)
 Prepare for the next frame/page in the image file. More...
 
uint16_t gdispImageGetPaletteSize (gdispImage *img)
 Get the number of entries in the color palette. More...
 
color_t gdispImageGetPalette (gdispImage *img, uint16_t index)
 Get an entry in the color palette. More...
 
bool_t gdispImageAdjustPalette (gdispImage *img, uint16_t index, color_t 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 uint16_t gdispImageType
 The type of image. More...
 
typedef uint16_t gdispImageError
 An image error code. More...
 
typedef uint16_t gdispImageFlags
 Image flags. More...
 
typedef struct gdispImage gdispImage
 The structure for an image. More...
 

Function Documentation

gdispImageError gdispGImageDraw ( GDisplay *  g,
gdispImage img,
coord_t  x,
coord_t  y,
coord_t  cx,
coord_t  cy,
coord_t  sx,
coord_t  sy 
)

Draw the image.

Returns
GDISP_IMAGE_ERR_OK (0) on success or an error code.
Parameters
[in]gThe display to draw on
[in]imgThe image structure
[in]x,yThe screen location to draw the image
[in]cx,cyThe area on the screen to draw
[in]sx,syThe 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)

Referenced by gwinProgressbarDraw_Std(), and gwinSliderDraw_Std().

bool_t gdispImageAdjustPalette ( gdispImage img,
uint16_t  index,
color_t  newColor 
)

Modify an entry in the color palette.

Returns
TRUE on success, FALSE otherwise.
Parameters
[in]imgThe image structure
[in]indexThe index of the color palette entry
[in]newColorThe new color value of the specified entry
Precondition
gdispImageOpen() must have returned successfully.
Note
This function will return FALSE if the index is out of bounds or if the image doesn't use a color palette.
gdispImageError gdispImageCache ( gdispImage 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]imgThe 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.
void gdispImageClose ( gdispImage img)

Close an image and release any dynamically allocated working storage.

Parameters
[in]imgThe image structure
Precondition
gdispImageOpenFile() must have returned successfully.
Note
Also calls the IO close function (if it hasn't already been called).
color_t gdispImageGetPalette ( gdispImage img,
uint16_t  index 
)

Get an entry in the color palette.

Returns
The color value at a given position in the color palette.
Parameters
[in]imgThe image structure
[in]indexThe 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.
uint16_t gdispImageGetPaletteSize ( gdispImage 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]imgThe image structure
Precondition
gdispImageOpen() must have returned successfully.
void gdispImageInit ( gdispImage img)

Initialise a gdispImage object.

Parameters
[in]imgThe image structure to initialise
bool_t gdispImageIsOpen ( gdispImage img)

Is an image open.

Returns
TRUE if the image is currently open.
Parameters
[in]imgThe 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.
delaytime_t gdispImageNext ( gdispImage 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 TIME_IMMEDIATE and TIME_INFINITE.
Parameters
[in]imgThe image structure
Precondition
gdispImageOpen() must have returned successfully.
Note
It will return TIME_IMMEDIATE if the first frame/page hasn't been drawn or if the next frame should be drawn immediately.
It will return TIME_INFINITE if another image frame doesn't exist or an error has occurred.
Images that support multiple pages (eg TIFF files) will return TIME_IMMEDIATE between pages and then TIME_INFINITE when there are no more pages.
An image that displays a looped animation will never return TIME_INFINITE unless it gets an error.
Calling gdispImageDraw() after getting a TIME_INFINITE will go back to drawing the first frame/page.
gdispImageError gdispImageOpenGFile ( gdispImage 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]imgThe image structure
[in]fThe 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 gdispImage 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.
void gdispImageSetBgColor ( gdispImage img,
color_t  bgcolor 
)

Set the background color of the image.

Parameters
[in]imgThe image structure
[in]bgcolorThe 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

#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 TRUE. This only makes sense on the ChibiOS operating system.
Parameters
[in]imgThe image structure
[in]BaseFileStreamPtrA pointer to an open BaseFileStream
Note
This function just opens the GFILE using the basefilestream and passes it to gdispImageOpenGFile().

Definition at line 138 of file gdisp_image.h.

#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]imgThe image structure
[in]filenameThe filename to open
Note
This function just opens the GFILE using the filename and passes it to gdispImageOpenGFile().

Definition at line 123 of file gdisp_image.h.

#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 TRUE
Parameters
[in]imgThe image structure
[in]ptrA 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 152 of file gdisp_image.h.

Typedef Documentation

typedef struct gdispImage gdispImage

The structure for an image.

typedef uint16_t gdispImageError

An image error code.

Definition at line 37 of file gdisp_image.h.

typedef uint16_t gdispImageFlags

Image flags.

Definition at line 51 of file gdisp_image.h.

typedef uint16_t gdispImageType

The type of image.

Definition at line 26 of file gdisp_image.h.