Atmel Software Framework

gfx.h File Reference

Graphical library API header file.

This files includes the correct header files for the graphics service

Copyright (c) 2012-2015 Atmel Corporation. All rights reserved.

#include <assert.h>
#include <compiler.h>
#include <stdint.h>
#include "gfx_hx8347a_et024006dhu.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.

#define GFX_OCTANT1   (1 << 1)

Bitmask for drawing circle octant 1.

#define GFX_OCTANT2   (1 << 2)

Bitmask for drawing circle octant 2.

#define GFX_OCTANT3   (1 << 3)

Bitmask for drawing circle octant 3.

#define GFX_OCTANT4   (1 << 4)

Bitmask for drawing circle octant 4.

#define GFX_OCTANT5   (1 << 5)

Bitmask for drawing circle octant 5.

#define GFX_OCTANT6   (1 << 6)

Bitmask for drawing circle octant 6.

#define GFX_OCTANT7   (1 << 7)

Bitmask for drawing circle octant 7.

#define GFX_QUADRANT0   (GFX_OCTANT0 | GFX_OCTANT1)

Bitmask for drawing circle quadrant 0.

#define GFX_QUADRANT1   (GFX_OCTANT2 | GFX_OCTANT3)

Bitmask for drawing circle quadrant 1.

#define GFX_QUADRANT2   (GFX_OCTANT4 | GFX_OCTANT5)

Bitmask for drawing circle quadrant 2.

#define GFX_QUADRANT3   (GFX_OCTANT6 | GFX_OCTANT7)

Bitmask for drawing circle quadrant 3.

#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_hx8347a_set_orientation(), gfx_ili9341_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.

#define PROGMEM_DECLARE (   type,
  name 
)    const type name
#define PROGMEM_PTR_T   const *
#define PROGMEM_READ_BYTE (   x)    *(x)
#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
r8-bit red value.
g8-bit green value.
b8-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
pixelsArray into which the pixel values are to be stored.
countNumber 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
pixelsAn array of pixel values in display native format.
countNumber 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
pixelsAn array of pixel values in display native format, stored in program (flash) memory.
countNumber 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
bmpPointer to bitmap gfx_bitmap
xDisplay X coordinate
yDisplay 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:

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
bmpPointer to bitmap
x1Output area left coordinate
y1Output area top coordinate
x2Output area right coordinate
y2Output area bottom coordinate
tile_origin_xTile origin left coordinate
tile_origin_yTile origin top coordinate

Referenced by win_draw_contents().

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
xX coordinate of the pixel to be drawn.
yY coordinate of the pixel to be drawn.
colorColor 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
xX coordinate of the pixel to be drawn.
yY coordinate of the pixel to be drawn.
colorColor 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
colorColor value in display native format.
countNumber 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 app_widget_launch(), draw_paint_pallet(), draw_pallet_labels(), get_finger_display_coordinates(), main(), mxt_handler(), read_touch_event(), show_out_of_memory_error(), ui_init(), update_pallet_selection(), win_hide(), win_init(), win_reset_root_geometry(), wtk_continue_drag(), wtk_start_drag(), and wtk_stop_drag().

gfx_color_t gfx_get_pixel ( gfx_coord_t  x,
gfx_coord_t  y 
)

Get the color of a pixel on the display.

Parameters
xX coordinate of the pixel to be sampled.
yY 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 app_widget_launch(), draw_paint_pallet(), get_finger_display_coordinates(), main(), mxt_handler(), read_touch_event(), show_out_of_memory_error(), ui_init(), win_hide(), win_init(), win_reset_root_geometry(), wtk_continue_drag(), wtk_start_drag(), and wtk_stop_drag().

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
bmpPointer to bitmap.
map_xX coordinate inside pixel buffer.
map_yY coordinate inside pixel buffer.
xX coordinate on screen.
yY coordinate on screen.
widthWidth of pixel rectangle to copy.
heightHeight 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
xBottom right x coordinate.
yBottom 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_xLeft edge of region.
min_yTop edge of region.
max_xRight edge of region.
max_yBottom edge of region.

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

Referenced by gfx_hx8347a_init(), gfx_hx8347a_set_orientation(), gfx_ili9341_init(), gfx_ili9341_set_orientation(), mxt_handler(), show_out_of_memory_error(), win_draw_contents(), win_hide(), wtk_continue_drag(), wtk_start_drag(), and wtk_stop_drag().

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_handlerPointer 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
x1Top left x coordinate.
y1Top left y coordinate.
x2Bottom right x coordinate.
y2Bottom right y coordinate.

Referenced by gfx_generic_draw_filled_rect(), gfx_hx8347a_draw_pixel(), gfx_hx8347a_get_pixel(), gfx_ili9341_draw_pixel(), and gfx_ili9341_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:

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
flagsA 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
xTop left x coordinate.
yTop left y coordinate.

Referenced by gfx_generic_get_pixmap(), gfx_generic_put_bitmap(), gfx_generic_put_pixmap(), gfx_hx8347a_draw_line_pixel(), and gfx_ili9341_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.