Hardware Agnostic Graphics Library

HAGL is a lightweight hardware agnostics graphics library. It supports basic geometric primitives, bitmaps, blitting, fixed width fonts. Library tries to stay lightweight but targets reasonably powerful microchips such as ESP32. There is no dynamic allocation.

This can still be considered work in progress. API should be 90% stable.

Backend

To use HAGL you must provide a backend. The backend must provide atleast a function for putting a pixel. If nothing else is provided all higher level graphical functions will use this function to draw the primitives. While proper documentation is lacking see the example backend implementations for GD, SDL2, ESP-IDF (Ilitek, Sitronix, Galaxycore), ESP-IDF (Solomon), Nuclei RISC-V SDK, Raspberry Pi Pico SDK and Raspberry Pi Pico VGA board.

Usage

High level functions are pretty self explanatory. For example applications see Pico Effects, ESP Effects, SDL2 Effects, ESP GFX, and GD32V Effects.

Lifecycle

Before you start drawing you should call hagl_init(). Some HAL configurations require you to call hagl_flush() to update the contents of the screen. Before exiting your program it is good idea to call hagl_close()to clean things up.

#include <hagl_hal.h>
#include <hagl.h>

hagl_backend_t *display = hagl_init();

/* Main loop. */
while (1) {
    hagl_clear(display);
    hagl_load_image(display, 0, 0, "/sdcard/hello.jpg");
    hagl_flush(display);
};

hagl_close(display);

Colors

HAL defines what kind of pixel format is used. Most common is RGB565 which is represented by two bytes. If you are sure you will be using only RGB565 colors you could use the following shortcut to create a random color.

hagl_color_t color = rand() % 0xffff;

To write portable code which can be run with different pixel formats use the following instead.

uint8_t r = rand() % 255;
uint8_t g = rand() % 255;
uint8_t b = rand() % 255;
hagl_color_t color = hagl_color(display, r, g, b);

Put a pixel

for (uint32_t i = 1; i < 100000; i++) {
    int16_t x0 = rand() % display->width;
    int16_t y0 = rand() % display->height;
    hagl_color_t color = rand() % 0xffff;

    hagl_put_pixel(display, x0, y0, color);
}

Get a pixel

int16_t x0 = rand() % display->width;
int16_t y0 = rand() % display->height;

hagl_color_t pixel = hagl_get_pixel(display, x0, y0);

Note that if requesting coordinates outside the clip window color black is returned. This behaviour is unoptimal and might change in the future.

Draw a line

for (uint16_t i = 1; i < 1000; i++) {
    int16_t x0 = rand() % display->width;
    int16_t y0 = rand() % display->height;
    int16_t x1 = rand() % display->width;
    int16_t y1 = rand() % display->height;
    hagl_color_t color = rand() % 0xffff;

    hagl_draw_line(display, x0, y0, x1, y1, color);
}

Draw a horizontal line

for (uint16_t i = 1; i < 1000; i++) {
    int16_t x0 = rand() % (display->width / 2);
    int16_t y0 = rand() % display->height;
    int16_t x1 = rand() % (display->width / 2);
    int16_t width = rand() % (display->width - x0);
    hagl_color_t color = rand() % 0xffff;

    /* First two are aliases. */
    hagl_draw_hline(display, x0, y0, width, color);
    hagl_draw_hline_xyw(display, x0, y0, width, color);

    hagl_draw_hline_xyx(display, x0, y0, x1, color);
}

Draw a vertical line

for (uint16_t i = 1; i < 1000; i++) {
    int16_t x0 = rand() % display->width;
    int16_t y0 = rand() % (display->height / 2);
    int16_t y1 = rand() % (display->height / 2);
    int16_t height = rand() % (display->height - y0);
    hagl_color_t color = rand() % 0xffff;

    /* First two are aliases. */
    hagl_draw_vline(display, x0, y0, height, color);
    hagl_draw_vline_xyh(display, x0, y0, height, color);

    hagl_draw_vline_xyy(display, x0, y0, y1, color);
}

Draw a circle

for (uint16_t i = 1; i < 500; i++) {
    int16_t x0 = display->width / 2;
    int16_t y0 = display->height / 2;
    int16_t radius = rand() % display->width;
    hagl_color_t color = rand() % 0xffff;

    hagl_draw_circle(display, x0, y0, radius, color);
}

Draw a filled circle

for (uint16_t i = 1; i < 500; i++) {
    int16_t x0 = rand() % display->width;
    int16_t y0 = rand() % display->height;
    int16_t radius = rand() % 100;
    hagl_color_t color = rand() % 0xffff;

    hagl_fill_circle(display, x0, y0, radius, color);
}

Draw an ellipse

for (uint16_t i = 1; i < 500; i++) {
    int16_t x0 = display->width / 2;
    int16_t y0 = display->height / 2;
    int16_t rx = rand() % display->width;
    int16_t ry = rand() % display->height;
    hagl_color_t color = rand() % 0xffff;

    hagl_draw_ellipse(display, x0, y0, rx, ry, color);
}

Draw a filled ellipse

for (uint16_t i = 1; i < 500; i++) {
    int16_t x0 = rand() % display->width;
    int16_t y0 = rand() % display->height;
    int16_t rx = rand() % display->width / 4;
    int16_t ry = rand() % display->height / 4;
    hagl_color_t color = rand() % 0xffff;

    hagl_fill_ellipse(display, x0, y0, rx, ry, color);
}

Draw a triangle

int16_t x0 = rand() % display->width;
int16_t y0 = rand() % display->height;
int16_t x1 = rand() % display->width;
int16_t y1 = rand() % display->height;
int16_t x2 = rand() % display->width;
int16_t y2 = rand() % display->height;
hagl_color_t color = rand() % 0xffff;

hagl_draw_triangle(display, x0, y0, x1, y1, x2, y2, color);

Draw a filled triangle

int16_t x0 = rand() % display->width;
int16_t y0 = rand() % display->height;
int16_t x1 = rand() % display->width;
int16_t y1 = rand() % display->height;
int16_t x2 = rand() % display->width;
int16_t y2 = rand() % display->height;
hagl_color_t color = rand() % 0xffff;

hagl_fill_triangle(display, x0, y0, x1, y1, x2, y2, color);

Draw a rectangle

for (uint16_t i = 1; i < 50; i++) {
    int16_t x0 = rand() % display->width;
    int16_t y0 = rand() % display->height;
    int16_t x1 = rand() % display->width;
    int16_t y1 = rand() % display->height;
    int16_t w = rand() % display->width / 2;
    int16_t h = rand() % display->height / 2;
    hagl_color_t color = rand() % 0xffff;

    /* First two are aliases. */
    hagl_draw_rectangle(display, x0, y0, x1, y1, color);
    hagl_draw_rectangle_xyxy(display, x0, y0, x1, y1, color);

    hagl_draw_rectangle_xywh(display, x0, y0, w, h, color);
}

Draw a filled rectangle

for (uint16_t i = 1; i < 10; i++) {
    int16_t x0 = rand() % display->width;
    int16_t y0 = rand() % display->height;
    int16_t x1 = rand() % display->width;
    int16_t y1 = rand() % display->height;
    int16_t w = rand() % display->width / 2;
    int16_t h = rand() % display->height / 2;
    hagl_color_t color = rand() % 0xffff;

    /* First two are aliases. */
    hagl_fill_rectangle(display, x0, y0, x1, y1, color);
    hagl_fill_rectangle_xyxy(display, x0, y0, x1, y1, color);

    hagl_fill_rectangle_xywh(display, x0, y0, w, h, color);
}

Draw a rounded rectangle

for (uint16_t i = 1; i < 30; i++) {
    int16_t x0 = rand() % display->width;
    int16_t y0 = rand() % display->height;
    int16_t x1 = rand() % display->width;
    int16_t y1 = rand() % display->height;
    int16_t w = rand() % display->width / 2;
    int16_t h = rand() % display->height / 2;
    int16_t r = 10
    hagl_color_t color = rand() % 0xffff;

    /* First two are aliases. */
    hagl_draw_rounded_rectangle(display, x0, y0, x1, y1, r, color);
    hagl_draw_rounded_rectangle_xyxy(display, x0, y0, x1, y1, r, color);

    hagl_draw_rounded_rectangle_xywh(display, x0, y0, w, h, r, color);
}

Draw a filled rounded rectangle

for (uint16_t i = 1; i < 30; i++) {
    int16_t x0 = rand() % display->width;
    int16_t y0 = rand() % display->height;
    int16_t x1 = rand() % display->width;
    int16_t y1 = rand() % display->height;
    int16_t w = rand() % display->width / 2;
    int16_t h = rand() % display->height / 2;
    int16_t r = 10
    hagl_color_t color = rand() % 0xffff;

    /* First two are aliases. */
    hagl_fill_rounded_rectangle(display, x0, y0, x1, y1, r, color);
    hagl_fill_rounded_rectangle_xyxy(display, x0, y0,