gfx.h File Reference

Graphical library API header file.

This files includes the correct header files for the graphics service

Copyright (c) 2012-2018 Microchip Technology Inc. and its subsidiaries.

#include <assert.h>
#include <compiler.h>
#include <stdint.h>
#include "gfx_ili9488_90_00028_a0.h"
#include "gfx_generic.h"

Macros
#define	CONF_GFX_USE_CLIPPING
#define	PROGMEM_DECLARE(type, name)   const type name
#define	PROGMEM_PTR_T   const *
#define	PROGMEM_READ_BYTE(x)   *(x)
#define	PROGMEM_T   const
Standard Color Definitions
#define	GFX_COLOR_BLACK   GFX_COLOR( 0, 0, 0)
#define	GFX_COLOR_WHITE   GFX_COLOR(255, 255, 255)
#define	GFX_COLOR_GRAY   GFX_COLOR(128, 128, 128)
#define	GFX_COLOR_RED   GFX_COLOR(255, 0, 0)
#define	GFX_COLOR_DK_RED   GFX_COLOR(128, 0, 0)
#define	GFX_COLOR_GREEN   GFX_COLOR( 0, 255, 0)
#define	GFX_COLOR_DK_GREEN   GFX_COLOR( 0, 128, 0)
#define	GFX_COLOR_BLUE   GFX_COLOR( 0, 0, 255)
#define	GFX_COLOR_DK_BLUE   GFX_COLOR( 0, 0, 128)
#define	GFX_COLOR_MAGENTA   GFX_COLOR(255, 0, 255)
#define	GFX_COLOR_DK_MAGENTA   GFX_COLOR(128, 0, 128)
#define	GFX_COLOR_YELLOW   GFX_COLOR(255, 255, 0)
#define	GFX_COLOR_DK_YELLOW   GFX_COLOR(128, 128, 0)
#define	GFX_COLOR_CYAN   GFX_COLOR( 0, 255, 255)
#define	GFX_COLOR_DK_CYAN   GFX_COLOR( 0, 128, 128)
Circle Sector Definitions
#define	GFX_OCTANT0   (1 << 0)
	Bitmask for drawing circle octant 0. More...
#define	GFX_OCTANT1   (1 << 1)
	Bitmask for drawing circle octant 1. More...
#define	GFX_OCTANT2   (1 << 2)
	Bitmask for drawing circle octant 2. More...
#define	GFX_OCTANT3   (1 << 3)
	Bitmask for drawing circle octant 3. More...
#define	GFX_OCTANT4   (1 << 4)
	Bitmask for drawing circle octant 4. More...
#define	GFX_OCTANT5   (1 << 5)
	Bitmask for drawing circle octant 5. More...
#define	GFX_OCTANT6   (1 << 6)
	Bitmask for drawing circle octant 6. More...
#define	GFX_OCTANT7   (1 << 7)
	Bitmask for drawing circle octant 7. More...
#define	GFX_QUADRANT0   (GFX_OCTANT0 | GFX_OCTANT1)
	Bitmask for drawing circle quadrant 0. More...
#define	GFX_QUADRANT1   (GFX_OCTANT2 | GFX_OCTANT3)
	Bitmask for drawing circle quadrant 1. More...
#define	GFX_QUADRANT2   (GFX_OCTANT4 | GFX_OCTANT5)
	Bitmask for drawing circle quadrant 2. More...
#define	GFX_QUADRANT3   (GFX_OCTANT6 | GFX_OCTANT7)
	Bitmask for drawing circle quadrant 3. More...
#define	GFX_LEFTHALF   (GFX_QUADRANT3 | GFX_QUADRANT0)
	Bitmask for drawing left half of circle. More...
#define	GFX_TOPHALF   (GFX_QUADRANT0 | GFX_QUADRANT1)
	Bitmask for drawing top half of circle. More...
#define	GFX_RIGHTHALF   (GFX_QUADRANT1 | GFX_QUADRANT2)
	Bitmask for drawing right half of circle. More...
#define	GFX_BOTTOMHALF   (GFX_QUADRANT2 | GFX_QUADRANT3)
	Bitmask for drawing bottom half of circle. More...
#define	GFX_WHOLE   0xFF
	Bitmask for drawing whole circle. More...
Flags for gfx_set_orientation()
#define	GFX_FLIP_X   1
	Bitmask for flipping X for gfx_set_orientation() More...
#define	GFX_FLIP_Y   2
	Bitmask for flipping Y for gfx_set_orientation() More...
#define	GFX_SWITCH_XY   4
	Bitmask for swapping X and Y for gfx_set_orientation() More...

Functions
Bitmap functions and structures
void	gfx_draw_bitmap (const struct gfx_bitmap *bmp, gfx_coord_t x, gfx_coord_t y)
	Draw a bitmap. More...
void	gfx_draw_bitmap_tiled (const struct gfx_bitmap *bmp, gfx_coord_t x1, gfx_coord_t y1, gfx_coord_t x2, gfx_coord_t y2, gfx_coord_t tile_origin_x, gfx_coord_t tile_origin_y)
	Draw a bitmap to the screen tiled to cover the output area. More...
void	gfx_put_bitmap (const struct gfx_bitmap *bmp, gfx_coord_t map_x, gfx_coord_t map_y, gfx_coord_t x, gfx_coord_t y, gfx_coord_t width, gfx_coord_t height)
	Write a rectangular block of pixels from a bitmap to the screen. More...
Display driver management functions
void	gfx_sync (void)
	Synchronize access to the display. More...
Display Geometry
void	gfx_set_orientation (uint8_t flags)
	Change display orientation. More...
gfx_coord_t	gfx_get_width (void)
	Return the current width of the screen. More...
gfx_coord_t	gfx_get_height (void)
	Return the current height of the screen. More...
Display Clipping
The display driver uses software and hardware clipping. In the graphics drivers software clipping is referred to as clipping and hardware clipping as limits. Software clipping is used to ensure that nothing outside the set region is draw to the screen by any of the drawing functions. Eliminating unwanted drawing to the display will give a higher performance on displays which has a low bandwidth from the CPU. Software is enabled by the CONF_GFX_USE_CLIPPING configuration symbol. Clipping region is set with the gfx_set_clipping() function. Hardware clipping is used in the supported display drivers to efficiently draw primitives on a subset of the display. Example: when drawing a filled rectangle the limits is set to the size of the rectangle, and the driver sends the correct number of pixels to fill the entire rectangle. Without hardware clipping/limits the driver will have to to move the graphics ram (GRAM) position/pointer manually. Hardware clipping/limits is not used like software clipping to eliminate drawing outside a given region. Hardware clipping is set with the gfx_set_top_left_limit, gfx_set_bottom_right_limit and gfx_set_limits functions. In display drivers that do not use hardware clipping these functions will not have any effect.
void	gfx_set_clipping (gfx_coord_t min_x, gfx_coord_t min_y, gfx_coord_t max_x, gfx_coord_t max_y)
	Set the clipping region. More...
void	gfx_set_top_left_limit (gfx_coord_t x, gfx_coord_t y)
	Set the top-left limit for the display. More...
void	gfx_set_bottom_right_limit (gfx_coord_t x, gfx_coord_t y)
	Set the bottom-right limit for the display. More...
void	gfx_set_limits (gfx_coord_t x1, gfx_coord_t y1, gfx_coord_t x2, gfx_coord_t y2)
	Set the limits for the display. More...
Low-level pixel drawing operations
gfx_color_t	gfx_color (uint8_t r, uint8_t g, uint8_t b)
	Generate native color value from R/G/B values. More...
void	gfx_draw_pixel (gfx_coord_t x, gfx_coord_t y, gfx_color_t color)
	Draw a single pixel on the screen. More...
void	gfx_draw_line_pixel (gfx_coord_t x, gfx_coord_t y, gfx_color_t color)
	Draw a single pixel on the screen. More...
gfx_color_t	gfx_get_pixel (gfx_coord_t x, gfx_coord_t y)
	Get the color of a pixel on the display. More...
void	gfx_duplicate_pixel (gfx_color_t color, uint32_t count)
	Draw multiple pixels all having the same color. More...
void	gfx_copy_pixels_to_screen (const gfx_color_t *pixels, uint32_t count)
	Copy a block of pixels from data memory to screen. More...
void	gfx_copy_progmem_pixels_to_screen (gfx_color_t PROGMEM_PTR_T pixels, uint32_t count)
	Copy a block of pixels from program memory to screen. More...
void	gfx_copy_pixels_from_screen (gfx_color_t *pixels, uint32_t count)
	Copy a block of pixels from screen to data memory. More...
void	gfx_set_ext_handler (gfx_ext_draw_handler_t gfx_ext_draw_handler)
	Set bitmap draw function with custom interface. More...

Variables
Screen geometry and clipping variables
These global variables should not be accessed directly. They cannot be marked as private/static since they are shared within multiple C files of the graphics drivers. Use gfx_set_clipping() to change clipping region.
gfx_coord_t	gfx_min_x
	Minimum X of current clipping region. More...
gfx_coord_t	gfx_min_y
	Maximum Y of current clipping region. More...
gfx_coord_t	gfx_max_x
	Minimum X of current clipping region. More...
gfx_coord_t	gfx_max_y
	Maximum Y of current clipping region. More...
gfx_coord_t	gfx_width
	Current width of screen. More...
gfx_coord_t	gfx_height
	Current height of screen. More...

#define CONF_GFX_USE_CLIPPING

#define GFX_BOTTOMHALF   (GFX_QUADRANT2 | GFX_QUADRANT3)

Bitmask for drawing bottom half of circle.

#define GFX_FLIP_X   1

Bitmask for flipping X for gfx_set_orientation()

#define GFX_FLIP_Y   2

Bitmask for flipping Y for gfx_set_orientation()

Referenced by main().

#define GFX_LEFTHALF   (GFX_QUADRANT3 | GFX_QUADRANT0)

Bitmask for drawing left half of circle.

#define GFX_OCTANT0   (1 << 0)

Bitmask for drawing circle octant 0.

Referenced by gfx_generic_draw_circle().

#define GFX_OCTANT1   (1 << 1)

Bitmask for drawing circle octant 1.

Referenced by gfx_generic_draw_circle().

#define GFX_OCTANT2   (1 << 2)

Bitmask for drawing circle octant 2.

Referenced by gfx_generic_draw_circle().

#define GFX_OCTANT3   (1 << 3)

Bitmask for drawing circle octant 3.

Referenced by gfx_generic_draw_circle().

#define GFX_OCTANT4   (1 << 4)

Bitmask for drawing circle octant 4.

Referenced by gfx_generic_draw_circle().

#define GFX_OCTANT5   (1 << 5)

Bitmask for drawing circle octant 5.

Referenced by gfx_generic_draw_circle().

#define GFX_OCTANT6   (1 << 6)

Bitmask for drawing circle octant 6.

Referenced by gfx_generic_draw_circle().

#define GFX_OCTANT7   (1 << 7)

Bitmask for drawing circle octant 7.

Referenced by gfx_generic_draw_circle().

#define GFX_QUADRANT0   (GFX_OCTANT0 | GFX_OCTANT1)

Bitmask for drawing circle quadrant 0.

Referenced by gfx_generic_draw_filled_circle().

#define GFX_QUADRANT1   (GFX_OCTANT2 | GFX_OCTANT3)

Bitmask for drawing circle quadrant 1.

Referenced by gfx_generic_draw_filled_circle().

#define GFX_QUADRANT2   (GFX_OCTANT4 | GFX_OCTANT5)

Bitmask for drawing circle quadrant 2.

Referenced by gfx_generic_draw_filled_circle().

#define GFX_QUADRANT3   (GFX_OCTANT6 | GFX_OCTANT7)

Bitmask for drawing circle quadrant 3.

Referenced by gfx_generic_draw_filled_circle().

#define GFX_RIGHTHALF   (GFX_QUADRANT1 | GFX_QUADRANT2)

Bitmask for drawing right half of circle.

#define GFX_SWITCH_XY   4

Bitmask for swapping X and Y for gfx_set_orientation()

Referenced by gfx_ili9488_set_orientation(), and main().

#define GFX_TOPHALF   (GFX_QUADRANT0 | GFX_QUADRANT1)

Bitmask for drawing top half of circle.

#define GFX_WHOLE   0xFF

Bitmask for drawing whole circle.

Referenced by main().

#define PROGMEM_DECLARE	(		type,
			name
	)		const type name

#define PROGMEM_PTR_T   const *

Referenced by gfx_draw_char_progmem(), gfx_draw_progmem_string_aligned(), gfx_generic_put_bitmap(), and gfx_get_progmem_string_bounding_box().

#define PROGMEM_READ_BYTE

(

x

)

*(x)

Referenced by gfx_draw_char_progmem(), gfx_draw_progmem_string_aligned(), and gfx_get_progmem_string_bounding_box().

#define PROGMEM_T   const

gfx_color_t gfx_color	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

Generate native color value from R/G/B values.

Converts 8-bit R/G/B values to a color value native to the display. The format of the resulting color value depends on the display.

The macro GFX_COLOR does the same, only allows the preprocessor to handle the calculations.

Parameters

r	8-bit red value.
g	8-bit green value.
b	8-bit blue value.

Returns

Color value in display native format.

Referenced by main().

void gfx_copy_pixels_from_screen	(	gfx_color_t *	pixels,
		uint32_t	count
	)

Copy a block of pixels from screen to data memory.

Copy a block of pixels from the screen into RAM, given current limits

Parameters

pixels	Array into which the pixel values are to be stored.
count	Number of pixels to copy into the array.

Referenced by gfx_generic_get_pixmap().

void gfx_copy_pixels_to_screen	(	const gfx_color_t *	pixels,
		uint32_t	count
	)

Copy a block of pixels from data memory to screen.

Copy pixels from RAM to the screen, given current limits.

Parameters

pixels	An array of pixel values in display native format.
count	Number of pixels to copy from the array.

Referenced by gfx_generic_put_bitmap(), and gfx_generic_put_pixmap().

void gfx_copy_progmem_pixels_to_screen	(	gfx_color_t PROGMEM_PTR_T	pixels,
		uint32_t	count
	)

Copy a block of pixels from program memory to screen.

Copy a block of pixels from program memory to screen, given current limits.

Parameters

pixels	An array of pixel values in display native format, stored in program (flash) memory.
count	Number of pixels to copy from the array.

Referenced by gfx_generic_put_bitmap().

void gfx_draw_bitmap	(	const struct gfx_bitmap *	bmp,
		gfx_coord_t	x,
		gfx_coord_t	y
	)

Draw a bitmap.

Draw a bitmap to the screen on the given display coordinates

Parameters

bmp	Pointer to bitmap gfx_bitmap
x	Display X coordinate
y	Display Y coordinate

Referenced by main().

void gfx_draw_bitmap_tiled	(	const struct gfx_bitmap *	bmp,
		gfx_coord_t	x1,
		gfx_coord_t	y1,
		gfx_coord_t	x2,
		gfx_coord_t	y2,
		gfx_coord_t	tile_origin_x,
		gfx_coord_t	tile_origin_y
	)

Draw a bitmap to the screen tiled to cover the output area.

The function starts at the tile origin and searches to find the coordinate closest to the top left of the output area that is a multiple of the bitmap width/height. It then draws the bitmap as many times as needed to cover the entire output area.

To draw a bitmap tiled on the entire screen, regardless of the bitmap size, the function can be used like this:

gfx_draw_bitmap_tiled(bmp, 0, 0, gfx_get_width(), gfx_get_height(), 0, ,0);

The function is used by the "window system" to redraw the background of a parent window when a transparent child window needs to be redrawn. In this case the full parent window does not need redrawing, only the area of the parent window that is under the child window. The tiles of the background image will for all windows start at the top left corner of the window, so the function is used like this:

gfx_draw_bitmap_tiled(parent_background_bmp,
                      child_window_x1, child_window_y1,
                      child_window_x2, child_window_y2,
                      parent_window_origin_x, parent_window_origin_y);

Note

If CONF_GFX_USE_CLIPPING is used, the output is clipped to the output area and nothing will be drawn outside the output area.

Parameters

bmp	Pointer to bitmap
x1	Output area left coordinate
y1	Output area top coordinate
x2	Output area right coordinate
y2	Output area bottom coordinate
tile_origin_x	Tile origin left coordinate
tile_origin_y	Tile origin top coordinate

void gfx_draw_line_pixel	(	gfx_coord_t	x,
		gfx_coord_t	y,
		gfx_color_t	color
	)

Draw a single pixel on the screen.

This function draws a single pixel on screen only setting top limit which makes it more suitable for line drawing. If outside the clipping region, nothing is drawn.

Parameters

x	X coordinate of the pixel to be drawn.
y	Y coordinate of the pixel to be drawn.
color	Color value of the pixel in display native format.

Referenced by gfx_generic_draw_line().

void gfx_draw_pixel	(	gfx_coord_t	x,
		gfx_coord_t	y,
		gfx_color_t	color
	)

Draw a single pixel on the screen.

Draw a single pixel on screen setting top and bottom limits. If outside the clipping region, nothing is drawn.

Parameters

x	X coordinate of the pixel to be drawn.
y	Y coordinate of the pixel to be drawn.
color	Color value of the pixel in display native format.

Referenced by gfx_draw_char_hugemem(), gfx_draw_char_progmem(), gfx_generic_draw_circle(), gfx_generic_draw_filled_circle(), and main().

void gfx_duplicate_pixel	(	gfx_color_t	color,
		uint32_t	count
	)

Draw multiple pixels all having the same color.

Draw count pixels using color within the current clipping limits.

Parameters

color	Color value in display native format.
count	Number of times to write the color

Referenced by gfx_generic_draw_filled_rect().

gfx_coord_t gfx_get_height

(

void

)

Return the current height of the screen.

Return the current height of the screen for the current orientation. Screen can be rotated runtime on supported displays with gfx_set_orientation.

Returns

Height of the screen in pixels.

References gfx_height.

Referenced by main().

gfx_color_t gfx_get_pixel	(	gfx_coord_t	x,
		gfx_coord_t	y
	)

Get the color of a pixel on the display.

Parameters

x	X coordinate of the pixel to be sampled.
y	Y coordinate of the pixel to be sampled.

Returns

Color value of the pixel at (x, y) in display native format, or GFX_COLOR_INVALID if outside the clipping region.

gfx_coord_t gfx_get_width

(

void

)

Return the current width of the screen.

Return the current width of the screen for the current orientation. Screen can be rotated runtime on supported displays with gfx_set_orientation.

Returns

Width of the screen in pixels.

References gfx_width.

Referenced by main().

void gfx_put_bitmap	(	const struct gfx_bitmap *	bmp,
		gfx_coord_t	map_x,
		gfx_coord_t	map_y,
		gfx_coord_t	x,
		gfx_coord_t	y,
		gfx_coord_t	width,
		gfx_coord_t	height
	)

Write a rectangular block of pixels from a bitmap to the screen.

This function draws a subset of a bitmap to the screen. The subset is given by (map_x, map_y, width, height), and is outputted to the screen at the screen coordinates (x, y).

If the area to write is outside the clipping region, those pixels will not be written.

Note

This function fails if the width or height is negative or the pixel rectangle is outside the pixmap buffer extents. Clipping is only performed on the screen, not inside the pixmap buffer itself.

There is no checking if the pixel rectangle exceeds the bottom of the pixmap buffer.

Parameters

bmp	Pointer to bitmap.
map_x	X coordinate inside pixel buffer.
map_y	Y coordinate inside pixel buffer.
x	X coordinate on screen.
y	Y coordinate on screen.
width	Width of pixel rectangle to copy.
height	Height of pixel rectangle to copy.

Referenced by gfx_generic_draw_bitmap(), and gfx_generic_draw_bitmap_tiled().

void gfx_set_bottom_right_limit	(	gfx_coord_t	x,
		gfx_coord_t	y
	)

Set the bottom-right limit for the display.

Set bottom-right clipping limit for displays that needs to set a hardware clipping region.

Parameters

x	Bottom right x coordinate.
y	Bottom right y coordinate.

Referenced by gfx_generic_draw_line(), gfx_generic_get_pixmap(), gfx_generic_put_bitmap(), and gfx_generic_put_pixmap().

void gfx_set_clipping	(	gfx_coord_t	min_x,
		gfx_coord_t	min_y,
		gfx_coord_t	max_x,
		gfx_coord_t	max_y
	)

Set the clipping region.

Set the clipping region for all subsequent graphics operations. Nothing will be drawn outside the clipping region. Clipping is handled in software, and is enabled with CONF_GFX_USE_CLIPPING.

Parameters

min_x	Left edge of region.
min_y	Top edge of region.
max_x	Right edge of region.
max_y	Bottom edge of region.

References gfx_height, gfx_max_x, gfx_max_y, gfx_min_x, gfx_min_y, and gfx_width.

Referenced by gfx_ili9488_init(), and gfx_ili9488_set_orientation().

void gfx_set_ext_handler

(

gfx_ext_draw_handler_t

gfx_ext_draw_handler

)

Set bitmap draw function with custom interface.

Set bitmap draw function with customer interface. This allows to use the extended draw functions defined by the application. For example, do the draw bitmap function though a filesystem.

Parameters

gfx_ext_draw_handler

Pointer to custom bitmap draw handler.

void gfx_set_limits	(	gfx_coord_t	x1,
		gfx_coord_t	y1,
		gfx_coord_t	x2,
		gfx_coord_t	y2
	)

Set the limits for the display.

Set clipping limit for displays that needs to set a hardware clipping region.

Parameters

x1	Top left x coordinate.
y1	Top left y coordinate.
x2	Bottom right x coordinate.
y2	Bottom right y coordinate.

Referenced by gfx_generic_draw_filled_rect(), gfx_ili9488_draw_pixel(), and gfx_ili9488_get_pixel().

void gfx_set_orientation

(

uint8_t

flags

)

Change display orientation.

Changes the display orientation for displays that support this. Check the driver specific documentation if this is supported.

The following masks are available and can be ORed together:

• GFX_FLIP_X Flip X axis
• GFX_FLIP_Y Flip Y axis
• GFX_SWITCH_XY Switch X/Y

Note that rotating the screen 90 degrees means switching X/Y and mirroring one of the axes. It is not enough to just switch X/Y.

Parameters

flags

A bitmask of which axes to flip and/or switch.

Referenced by main().

void gfx_set_top_left_limit	(	gfx_coord_t	x,
		gfx_coord_t	y
	)

Set the top-left limit for the display.

Set top-left clipping limit for displays that needs to set a hardware clipping region.

Parameters

x	Top left x coordinate.
y	Top left y coordinate.

Referenced by gfx_generic_get_pixmap(), gfx_generic_put_bitmap(), gfx_generic_put_pixmap(), and gfx_ili9488_draw_line_pixel().

void gfx_sync

(

void

)

Synchronize access to the display.

In case of a graphics driver implementation that queues graphics operations, this function will make sure all pending operations are completed before exiting. That way, if you want to read pixels from the display, you can be sure that the display information is fresh and updated. For implementations that does not queue operations, this function may do nothing, but for portability it should always be called before reading pixels, or performing other operations which rely on all pending drawing operations having actually been completed.

gfx_coord_t gfx_max_x

Minimum X of current clipping region.

Referenced by gfx_generic_draw_filled_rect(), gfx_generic_get_pixmap(), gfx_generic_put_bitmap(), gfx_generic_put_pixmap(), gfx_ili9488_draw_line_pixel(), gfx_ili9488_draw_pixel(), gfx_ili9488_get_pixel(), and gfx_set_clipping().

gfx_coord_t gfx_max_y

Maximum Y of current clipping region.

Referenced by gfx_generic_draw_filled_rect(), gfx_generic_get_pixmap(), gfx_generic_put_bitmap(), gfx_generic_put_pixmap(), gfx_ili9488_draw_line_pixel(), gfx_ili9488_draw_pixel(), gfx_ili9488_get_pixel(), and gfx_set_clipping().

gfx_coord_t gfx_min_x

Minimum X of current clipping region.

Referenced by gfx_generic_draw_filled_rect(), gfx_generic_get_pixmap(), gfx_generic_put_bitmap(), gfx_generic_put_pixmap(), gfx_ili9488_draw_line_pixel(), gfx_ili9488_draw_pixel(), gfx_ili9488_get_pixel(), and gfx_set_clipping().

gfx_coord_t gfx_min_y

Maximum Y of current clipping region.

Referenced by gfx_generic_draw_filled_rect(), gfx_generic_get_pixmap(), gfx_generic_put_bitmap(), gfx_generic_put_pixmap(), gfx_ili9488_draw_line_pixel(), gfx_ili9488_draw_pixel(), gfx_ili9488_get_pixel(), and gfx_set_clipping().