API reference

Every public function, grouped by header. Coordinates are in pixels with the origin at the top-left corner; every drawing call is clipped to the 240 x 240 screen.

Conventions

Colours are gfx_color_t, an RGB565 uint16_t. Build them with GFX_RGB(r, g, b) (components 0 to 255) or GFX_HEX(0xRRGGBB).
x, y is the top-left corner of rectangles, images and text. Circles and arcs take their centre cx, cy.
Angles are in degrees: 0 points up and positive angles run clockwise.
Strings are UTF-8 and limited to code points up to U+00FF.

Port: `gfx_port.h`

Function	Description
`void gfx_port_cmd(uint8_t command)`	Write one command byte (A0 or D/C low). You implement it.
`void gfx_port_data(uint16_t data)`	Write one data word (A0 or D/C high): an 8-bit parameter after CASET or RASET, a 16-bit pixel after RAMWR. You implement it.

Core: `gfx_core.h`

Function or macro	Description
`GFX_WIDTH`, `GFX_HEIGHT`	Screen size, 240 and 240.
`GFX_VERSION`	Library version string.
`GFX_RGB(r, g, b)`, `GFX_HEX(rgb)`	Build an RGB565 colour.
`GFX_BLACK`, `GFX_WHITE`	Colour constants.
`void gfx_set_window(x0, y0, x1, y1)`	Send CASET, RASET and RAMWR. Does not clip.
`void gfx_push(color)`	Send one pixel inside the current window.
`void gfx_push_repeat(color, count)`	Send `count` copies of a colour.
`int gfx_clip_rect(int x, int y, int w, int h)`	Clip a rectangle to the screen. Returns 0 if nothing is left.
`void gfx_pixel(x, y, color)`	Draw one pixel (costs 12 bus writes).
`void gfx_fill_rect(x, y, w, h, color)`	Filled rectangle, one window and one burst.
`void gfx_fill_screen(color)`	Fill the whole screen.
`void gfx_hline(x, y, w, color)`, `void gfx_vline(x, y, h, color)`	Horizontal and vertical lines.
`gfx_color_t gfx_blend(a, b, t)`	Mix two colours; `t` = 0 gives `a`, 255 gives `b`.
`gfx_color_t gfx_lighten(c, amount)`, `gfx_darken(c, amount)`	Mix with white or black.
`void gfx_fill_rect_vgradient(x, y, w, h, top, bottom)`	Vertical gradient, one row per step.
`void gfx_fill_rect_hgradient(x, y, w, h, left, right)`	Horizontal gradient, one column per step.

Shapes: `gfx_shapes.h`

Function	Description
`void gfx_line(x0, y0, x1, y1, color)`	One-pixel line, drawn as runs.
`void gfx_line_thick(x0, y0, x1, y1, thickness, color)`	Thick line with round caps.
`void gfx_rect(x, y, w, h, color)`	One-pixel rectangle outline.
`void gfx_rect_thick(x, y, w, h, thickness, color)`	Outline whose border grows inwards.
`void gfx_round_rect(x, y, w, h, radius, thickness, color)`	Rounded outline.
`void gfx_fill_round_rect(x, y, w, h, radius, color)`	Filled rounded rectangle; the radius is clamped to half the shorter side.
`void gfx_fill_round_rect_vgradient(x, y, w, h, radius, top, bottom)`	Rounded rectangle with a vertical gradient.
`void gfx_circle(cx, cy, radius, color)`	One-pixel circle outline.
`void gfx_fill_circle(cx, cy, radius, color)`	Filled circle.
`void gfx_ring(cx, cy, radius, thickness, color)`	Ring; the thickness grows inwards.
`void gfx_arc(cx, cy, radius, thickness, start_deg, end_deg, color)`	Ring segment between two angles.
`void gfx_triangle(x0, y0, x1, y1, x2, y2, color)`	Triangle outline.
`void gfx_fill_triangle(x0, y0, x1, y1, x2, y2, color)`	Filled triangle.
`void gfx_polygon(const gfx_point_t *points, int count, color)`	Polygon outline.
`void gfx_fill_polygon(const gfx_point_t *points, int count, color)`	Filled polygon, even-odd rule, up to 16 vertices.
`uint32_t gfx_isqrt(uint32_t value)`	Integer square root (floor).
`int gfx_sin_q14(int degrees)`, `int gfx_cos_q14(int degrees)`	Sine and cosine scaled by 16384.

Text: `gfx_text.h`

Function	Description
`int gfx_text_width(const char text, const gfx_font_t font)`	Width of a string in pixels.
`int gfx_text(x, y, text, font, fg, bg)`	Draw smooth text over a known background. Returns the x coordinate after the last glyph.
`int gfx_text_t(x, y, text, font, fg)`	Transparent background, no smoothing. Returns the x coordinate after the last glyph.
`void gfx_text_box(x, y, w, text, font, fg, bg, align)`	Align text in a box of width `w` and paint the leftover background. `align` is `GFX_ALIGN_LEFT`, `GFX_ALIGN_CENTER` or `GFX_ALIGN_RIGHT`.
`char gfx_int_to_str(int32_t value, char buf)`	Integer to text without printf. The buffer needs at least 12 bytes.

Images and icons: `gfx_image.h`

Function	Description
`void gfx_draw_image(x, y, w, h, const uint16_t *pixels)`	Draw a full RGB565 image stored in flash.
`void gfx_draw_icon(x, y, const gfx_image_a4_t *icon, fg, bg)`	4-bit opacity icon, smooth over a known background.
`void gfx_draw_icon_t(x, y, icon, fg)`	Icon without a background, no smoothing.
`void gfx_draw_bitmap1(x, y, w, h, const uint8_t *bits, fg, bg)`	1-bit bitmap, most significant bit on the left.
`void gfx_draw_bitmap1_t(x, y, w, h, bits, fg)`	1-bit bitmap, only the set bits are painted.

Convert your own pictures with tools/img2c.py: python3 tools/img2c.py photo.png my_photo --size 120x80 writes my_photo.c and my_photo.h, and --mono produces a 1-bit bitmap.

Fonts: `gfx_fonts.h`

Object	Line height	Characters
`gfx_font_sans_12`	15 px	U+0020 to U+007E, U+00A0 to U+00FF
`gfx_font_sans_16`	19 px	U+0020 to U+007E, U+00A0 to U+00FF
`gfx_font_sans_24`	29 px	U+0020 to U+007E, U+00A0 to U+00FF
`gfx_font_sans_bold_16`	19 px	U+0020 to U+007E, U+00A0 to U+00FF
`gfx_font_sans_bold_24`	29 px	U+0020 to U+007E, U+00A0 to U+00FF
`gfx_font_sans_bold_48`	57 px	space to colon (digits) and the degree sign

Icons: `gfx_icons.h`

32 icons of 32 x 32 pixels, 4 bits of opacity each. Pass them to gfx_draw_icon(), gfx_widget_button(), gfx_widget_list_item() and gfx_widget_tabbar().

gfx_icon_home, gfx_icon_gear, gfx_icon_wifi, gfx_icon_battery, gfx_icon_bell, gfx_icon_user, gfx_icon_lock, gfx_icon_heart, gfx_icon_star, gfx_icon_sun, gfx_icon_moon, gfx_icon_check, gfx_icon_close, gfx_icon_plus, gfx_icon_minus, gfx_icon_arrow_left, gfx_icon_arrow_right, gfx_icon_arrow_up, gfx_icon_arrow_down, gfx_icon_play, gfx_icon_pause, gfx_icon_search, gfx_icon_mail, gfx_icon_clock, gfx_icon_bolt, gfx_icon_power, gfx_icon_thermometer, gfx_icon_drop, gfx_icon_menu, gfx_icon_info, gfx_icon_warning, gfx_icon_pin.

All 32 icons drawn in a grid on the Icons demo page — The Icons demo page.

Widgets: `gfx_widgets.h`

Widgets draw with the colours of the active theme. Choose it with gfx_set_theme(&gfx_theme_dark) or gfx_set_theme(&gfx_theme_light), or define your own gfx_theme_t.

Function	Description
`void gfx_widget_panel(x, y, w, h, title)`	Card with an optional title (`NULL` for none).
`void gfx_widget_status_bar(title, battery_percent, wifi_on)`	32 px top bar.
`void gfx_widget_tabbar(y, h, icons, labels, count, selected)`	Bottom tab bar.
`void gfx_widget_button(x, y, w, h, label, icon, state)`	Button; `state` is `GFX_BUTTON_NORMAL`, `GFX_BUTTON_PRESSED` or `GFX_BUTTON_DISABLED`; `icon` may be `NULL`.
`void gfx_widget_switch(x, y, on)`	On/off switch, 48 x 26 px.
`void gfx_widget_checkbox(x, y, checked, label, bg)`	Check box with a label.
`void gfx_widget_slider(x, y, w, percent, bg)`	Slider, 24 px tall, 0 to 100 percent.
`void gfx_widget_badge(x, y, text, color)`	Small rounded label.
`void gfx_widget_progress(x, y, w, h, percent, color)`	Progress bar.
`void gfx_widget_ring(cx, cy, radius, thickness, percent, color, center_text)`	Ring gauge with optional centre text.
`void gfx_widget_chart(x, y, w, h, data, count, vmin, vmax, color)`	Line chart with a filled area.
`void gfx_widget_big_number(x, y, w, number, unit, color, bg)`	Large number with a unit, centred in a box.
`void gfx_widget_list_item(x, y, w, h, icon, title, detail, selected)`	List row with icon, title and right-aligned detail.

Demo: `gfx_demo.h`

Function	Description
`int gfx_demo_page_count(void)`	Number of pages (7).
`const char *gfx_demo_page_name(int page)`	Shapes, Text, Icons, Panel, Settings, Light theme, Images.
`void gfx_demo_page(int page)`	Draw a whole demo screen.

Self-test: `gfx_selftest.h`

Function	Description
`int gfx_selftest_page_count(void)`	Number of patterns (9).
`const char *gfx_selftest_page_name(int page)`	Colour bars, Gray ramp, Frame and corners, Grid, cross, circle, Nested rectangles, Text and icons, Solid red, Solid green, Solid blue.
`void gfx_selftest_page(int page)`	Draw a whole test pattern.

Single header: `lcd_gfx.h`

The same API in one file. Define GFX_IMPLEMENTATION before the include in exactly one source file; include it plainly everywhere else.

/* gfx_impl.c: the only file that holds the code */
#define GFX_IMPLEMENTATION
#include "lcd_gfx.h"

/* any other file */
#include "lcd_gfx.h"

Macro	Effect
`GFX_IMPLEMENTATION`	Compile the implementation in this translation unit.
`GFX_WITHOUT_DEMO`	Leave out the demo pages and their sample images. Define it for every file that includes the header.
`GFX_WITHOUT_SELFTEST`	Leave out the self-test patterns. Define it for every file that includes the header.

Regenerate the file after changing the sources with make header; make test fails if the committed file is out of date.

API reference

Conventions

Port: gfx_port.h

Core: gfx_core.h

Shapes: gfx_shapes.h

Text: gfx_text.h

Images and icons: gfx_image.h

Fonts: gfx_fonts.h

Icons: gfx_icons.h

Widgets: gfx_widgets.h

Demo: gfx_demo.h

Self-test: gfx_selftest.h

Single header: lcd_gfx.h