{"id":16320333,"url":"https://github.com/tuupola/hagl","last_synced_at":"2025-04-05T22:07:49.006Z","repository":{"id":36960507,"uuid":"130860355","full_name":"tuupola/hagl","owner":"tuupola","description":"Hardware Agnostic Graphics Library for embedded","archived":false,"fork":false,"pushed_at":"2024-05-03T10:32:46.000Z","size":285,"stargazers_count":306,"open_issues_count":17,"forks_count":49,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-10-11T22:44:09.113Z","etag":null,"topics":["esp-idf","esp32","gd32v","graphics-library","hagl","raspberry-pi-pico","rp2040"],"latest_commit_sha":null,"homepage":"https://www.appelsiini.net/tags/hagl/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuupola.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-24T13:40:51.000Z","updated_at":"2024-10-11T20:03:11.000Z","dependencies_parsed_at":"2024-06-24T01:01:45.445Z","dependency_job_id":"ecf741f5-84a8-43ca-8ecd-9f600a7cfe11","html_url":"https://github.com/tuupola/hagl","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fhagl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fhagl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fhagl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuupola%2Fhagl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuupola","download_url":"https://codeload.github.com/tuupola/hagl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406090,"owners_count":20933803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp-idf","esp32","gd32v","graphics-library","hagl","raspberry-pi-pico","rp2040"],"created_at":"2024-10-10T22:44:02.670Z","updated_at":"2025-04-05T22:07:48.971Z","avatar_url":"https://github.com/tuupola.png","language":"C","funding_links":[],"categories":["GUI"],"sub_categories":["Logging"],"readme":"# Hardware Agnostic Graphics Library\n\nHAGL 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.\n\nThis can still be considered work in progress. API should be 90% stable.\n\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)\n\n![Old school demo effects](https://appelsiini.net/img/2020/esp-effects.jpg)\n\n## Backend\n\nTo 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](https://github.com/tuupola/hagl_gd), [SDL2](https://github.com/tuupola/hagl_sdl2), [ESP-IDF (Ilitek, Sitronix, Galaxycore)](https://github.com/tuupola/hagl_esp_mipi), [ESP-IDF (Solomon)](https://github.com/tuupola/hagl_esp_solomon), [Nuclei RISC-V SDK](https://github.com/tuupola/hagl_gd32v_mipi), [Raspberry Pi Pico SDK](https://github.com/tuupola/hagl_pico_mipi) and [Raspberry Pi Pico VGA board](https://github.com/CHiPs44/hagl_pico_vgaboard).\n\n## Usage\n\nHigh level functions are pretty self explanatory. For example applications see [Pico Effects](https://github.com/tuupola/pico_effects), [ESP Effects](https://github.com/tuupola/esp_effects), [SDL2 Effects](https://github.com/tuupola/sdl2_effects), [ESP GFX](https://github.com/tuupola/esp_gfx), and [GD32V Effects](https://github.com/tuupola/gd32v_effects/).\n\n### Lifecycle\n\nBefore 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.\n\n```c\n#include \u003chagl_hal.h\u003e\n#include \u003chagl.h\u003e\n\nhagl_backend_t *display = hagl_init();\n\n/* Main loop. */\nwhile (1) {\n    hagl_clear(display);\n    hagl_load_image(display, 0, 0, \"/sdcard/hello.jpg\");\n    hagl_flush(display);\n};\n\nhagl_close(display);\n```\n\n### Colors\n\nHAL 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.\n\n```c\nhagl_color_t color = rand() % 0xffff;\n```\n\nTo write portable code which can be run with different pixel formats use the following instead.\n\n```c\nuint8_t r = rand() % 255;\nuint8_t g = rand() % 255;\nuint8_t b = rand() % 255;\nhagl_color_t color = hagl_color(display, r, g, b);\n```\n\n### Put a pixel\n\n```c\nfor (uint32_t i = 1; i \u003c 100000; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    hagl_color_t color = rand() % 0xffff;\n\n    hagl_put_pixel(display, x0, y0, color);\n}\n```\n\n![Random pixels](https://appelsiini.net/img/2020/hagl-put-pixel-gh.png)\n\n## Get a pixel\n\n```c\nint16_t x0 = rand() % display-\u003ewidth;\nint16_t y0 = rand() % display-\u003eheight;\n\nhagl_color_t pixel = hagl_get_pixel(display, x0, y0);\n```\n\nNote that if requesting coordinates outside the clip window color black is returned. This behaviour is unoptimal and might change in the future.\n\n### Draw a line\n\n```c\nfor (uint16_t i = 1; i \u003c 1000; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    int16_t x1 = rand() % display-\u003ewidth;\n    int16_t y1 = rand() % display-\u003eheight;\n    hagl_color_t color = rand() % 0xffff;\n\n    hagl_draw_line(display, x0, y0, x1, y1, color);\n}\n```\n\n![Random lines](https://www.appelsiini.net/img/2020/pod-draw-line.png)\n\n### Draw a horizontal line\n\n```c\nfor (uint16_t i = 1; i \u003c 1000; i++) {\n    int16_t x0 = rand() % (display-\u003ewidth / 2);\n    int16_t y0 = rand() % display-\u003eheight;\n    int16_t x1 = rand() % (display-\u003ewidth / 2);\n    int16_t width = rand() % (display-\u003ewidth - x0);\n    hagl_color_t color = rand() % 0xffff;\n\n    /* First two are aliases. */\n    hagl_draw_hline(display, x0, y0, width, color);\n    hagl_draw_hline_xyw(display, x0, y0, width, color);\n\n    hagl_draw_hline_xyx(display, x0, y0, x1, color);\n}\n```\n\n![Random horizontal lines](https://appelsiini.net/img/2020/pod-draw-hline.png)\n\n### Draw a vertical line\n\n```c\nfor (uint16_t i = 1; i \u003c 1000; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % (display-\u003eheight / 2);\n    int16_t y1 = rand() % (display-\u003eheight / 2);\n    int16_t height = rand() % (display-\u003eheight - y0);\n    hagl_color_t color = rand() % 0xffff;\n\n    /* First two are aliases. */\n    hagl_draw_vline(display, x0, y0, height, color);\n    hagl_draw_vline_xyh(display, x0, y0, height, color);\n\n    hagl_draw_vline_xyy(display, x0, y0, y1, color);\n}\n```\n\n![Random vertical lines](https://appelsiini.net/img/2020/pod-draw-vline.png)\n\n### Draw a circle\n\n```c\nfor (uint16_t i = 1; i \u003c 500; i++) {\n    int16_t x0 = display-\u003ewidth / 2;\n    int16_t y0 = display-\u003eheight / 2;\n    int16_t radius = rand() % display-\u003ewidth;\n    hagl_color_t color = rand() % 0xffff;\n\n    hagl_draw_circle(display, x0, y0, radius, color);\n}\n```\n\n![Random circle](https://appelsiini.net/img/2020/pod-draw-circle.png)\n\n### Draw a filled circle\n\n```c\nfor (uint16_t i = 1; i \u003c 500; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    int16_t radius = rand() % 100;\n    hagl_color_t color = rand() % 0xffff;\n\n    hagl_fill_circle(display, x0, y0, radius, color);\n}\n```\n\n![Random filled circle](https://appelsiini.net/img/2020/pod-fill-circle.png)\n\n### Draw an ellipse\n\n```c\nfor (uint16_t i = 1; i \u003c 500; i++) {\n    int16_t x0 = display-\u003ewidth / 2;\n    int16_t y0 = display-\u003eheight / 2;\n    int16_t rx = rand() % display-\u003ewidth;\n    int16_t ry = rand() % display-\u003eheight;\n    hagl_color_t color = rand() % 0xffff;\n\n    hagl_draw_ellipse(display, x0, y0, rx, ry, color);\n}\n```\n\n![Random ellipse](https://appelsiini.net/img/2020/hagl-draw-ellipse.png)\n\n### Draw a filled ellipse\n\n```c\nfor (uint16_t i = 1; i \u003c 500; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    int16_t rx = rand() % display-\u003ewidth / 4;\n    int16_t ry = rand() % display-\u003eheight / 4;\n    hagl_color_t color = rand() % 0xffff;\n\n    hagl_fill_ellipse(display, x0, y0, rx, ry, color);\n}\n```\n\n![Random filled ellipse](https://appelsiini.net/img/2020/hagl-fill-ellipse.png)\n\n### Draw a triangle\n\n```c\nint16_t x0 = rand() % display-\u003ewidth;\nint16_t y0 = rand() % display-\u003eheight;\nint16_t x1 = rand() % display-\u003ewidth;\nint16_t y1 = rand() % display-\u003eheight;\nint16_t x2 = rand() % display-\u003ewidth;\nint16_t y2 = rand() % display-\u003eheight;\nhagl_color_t color = rand() % 0xffff;\n\nhagl_draw_triangle(display, x0, y0, x1, y1, x2, y2, color);\n```\n\n![Random triangle](https://appelsiini.net/img/2020/pod-draw-triangle.png)\n\n### Draw a filled triangle\n\n```c\nint16_t x0 = rand() % display-\u003ewidth;\nint16_t y0 = rand() % display-\u003eheight;\nint16_t x1 = rand() % display-\u003ewidth;\nint16_t y1 = rand() % display-\u003eheight;\nint16_t x2 = rand() % display-\u003ewidth;\nint16_t y2 = rand() % display-\u003eheight;\nhagl_color_t color = rand() % 0xffff;\n\nhagl_fill_triangle(display, x0, y0, x1, y1, x2, y2, color);\n```\n\n![Random filled triangle](https://appelsiini.net/img/2020/pod-fill-triangle.png)\n\n### Draw a rectangle\n\n```c\nfor (uint16_t i = 1; i \u003c 50; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    int16_t x1 = rand() % display-\u003ewidth;\n    int16_t y1 = rand() % display-\u003eheight;\n    int16_t w = rand() % display-\u003ewidth / 2;\n    int16_t h = rand() % display-\u003eheight / 2;\n    hagl_color_t color = rand() % 0xffff;\n\n    /* First two are aliases. */\n    hagl_draw_rectangle(display, x0, y0, x1, y1, color);\n    hagl_draw_rectangle_xyxy(display, x0, y0, x1, y1, color);\n\n    hagl_draw_rectangle_xywh(display, x0, y0, w, h, color);\n}\n```\n\n![Random rectangle](https://appelsiini.net/img/2020/pod-draw-rectangle.png)\n\n### Draw a filled rectangle\n\n```c\nfor (uint16_t i = 1; i \u003c 10; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    int16_t x1 = rand() % display-\u003ewidth;\n    int16_t y1 = rand() % display-\u003eheight;\n    int16_t w = rand() % display-\u003ewidth / 2;\n    int16_t h = rand() % display-\u003eheight / 2;\n    hagl_color_t color = rand() % 0xffff;\n\n    /* First two are aliases. */\n    hagl_fill_rectangle(display, x0, y0, x1, y1, color);\n    hagl_fill_rectangle_xyxy(display, x0, y0, x1, y1, color);\n\n    hagl_fill_rectangle_xywh(display, x0, y0, w, h, color);\n}\n```\n\n![Random filled rectangle](https://appelsiini.net/img/2020/pod-fill-rectangle.png)\n\n### Draw a rounded rectangle\n\n```c\nfor (uint16_t i = 1; i \u003c 30; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    int16_t x1 = rand() % display-\u003ewidth;\n    int16_t y1 = rand() % display-\u003eheight;\n    int16_t w = rand() % display-\u003ewidth / 2;\n    int16_t h = rand() % display-\u003eheight / 2;\n    int16_t r = 10\n    hagl_color_t color = rand() % 0xffff;\n\n    /* First two are aliases. */\n    hagl_draw_rounded_rectangle(display, x0, y0, x1, y1, r, color);\n    hagl_draw_rounded_rectangle_xyxy(display, x0, y0, x1, y1, r, color);\n\n    hagl_draw_rounded_rectangle_xywh(display, x0, y0, w, h, r, color);\n}\n```\n\n![Random rounded rectangle](https://appelsiini.net/img/2020/hagl-draw-rounded-rectangle.png)\n\n### Draw a filled rounded rectangle\n\n```c\nfor (uint16_t i = 1; i \u003c 30; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    int16_t x1 = rand() % display-\u003ewidth;\n    int16_t y1 = rand() % display-\u003eheight;\n    int16_t w = rand() % display-\u003ewidth / 2;\n    int16_t h = rand() % display-\u003eheight / 2;\n    int16_t r = 10\n    hagl_color_t color = rand() % 0xffff;\n\n    /* First two are aliases. */\n    hagl_fill_rounded_rectangle(display, x0, y0, x1, y1, r, color);\n    hagl_fill_rounded_rectangle_xyxy(display, x0, y0, x1, y1, r, color);\n\n    hagl_fill_rounded_rectangle_xyxy(display, x0, y0, w, h, r, color);\n}\n```\n\n![Random filled rounded rectangle](https://appelsiini.net/img/2020/hagl-fill-rounded-rectangle.png)\n\n### Draw a polygon\n\nYou can draw polygons with unlimited number of vertices which are passed as an array. Pass the number of vertices as the first argument.\n\n```c\nint16_t x0 = rand() % display-\u003ewidth;\nint16_t y0 = rand() % display-\u003eheight;\nint16_t x1 = rand() % display-\u003ewidth;\nint16_t y1 = rand() % display-\u003eheight;\nint16_t x2 = rand() % display-\u003ewidth;\nint16_t y2 = rand() % display-\u003eheight;\nint16_t x3 = rand() % display-\u003ewidth;\nint16_t y3 = rand() % display-\u003eheight;\nint16_t x4 = rand() % display-\u003ewidth;\nint16_t y4 = rand() % display-\u003eheight;\nhagl_color_t color = rand() % 0xffff;\nint16_t vertices[10] = {x0, y0, x1, y1, x2, y2, x3, y3, x4, y4};\n\nhagl_draw_polygon(display, 5, vertices, color);\n```\n\n![Random polygon](https://appelsiini.net/img/2020/pod-draw-polygon.png)\n\n### Draw a filled polygon\n\nYou can draw filled polygons with up to 64 vertices which are passed as an array. First argument is the number of vertices. Polygon does **not** have to be concave.\n\n```c\nint16_t x0 = rand() % display-\u003ewidth;\nint16_t y0 = rand() % display-\u003eheight;\nint16_t x1 = rand() % display-\u003ewidth;\nint16_t y1 = rand() % display-\u003eheight;\nint16_t x2 = rand() % display-\u003ewidth;\nint16_t y2 = rand() % display-\u003eheight;\nint16_t x3 = rand() % display-\u003ewidth;\nint16_t y3 = rand() % display-\u003eheight;\nint16_t x4 = rand() % display-\u003ewidth;\nint16_t y4 = rand() % display-\u003eheight;\nhagl_color_t color = rand() % 0xffff;\nint16_t vertices[10] = {x0, y0, x1, y1, x2, y2, x3, y3, x4, y4};\n\nhagl_fill_polygon(display, 5, vertices, color);\n```\n\n![Random filled polygon](https://appelsiini.net/img/2020/pod-fill-polygon.png)\n\n### Put a single char\n\nThe library supports Unicode fonts in fontx format. It only includes three fonts by default. You can find more at [tuupola/embedded-fonts](https://github.com/tuupola/embedded-fonts) and [CHiPs44/fontx2-fonts](https://github.com/CHiPs44/fontx2-fonts) repositories.\n\n```c\nfor (uint16_t i = 1; i \u003c 10000; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    hagl_color_t color = rand() % 0xffff;\n    char code = rand() % 255;\n\n    hagl_put_char(display, code, x0, y0, color, font8x8);\n}\n```\n\n![Random chars](https://appelsiini.net/img/2020/hagl-put-char-gh.png)\n\n### Put a string\n\nThe library supports Unicode fonts in fontx format. It only includes three fonts by default. You can find more at [tuupola/embedded-fonts](https://github.com/tuupola/embedded-fonts) repository.\n\n```c\nfor (uint16_t i = 1; i \u003c 10000; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    hagl_color_t color = rand() % 0xffff;\n\n    hagl_put_text(display, u\"YO! MTV raps.\", x0, y0, color, font6x9);\n}\n```\n\n![Random strings](https://appelsiini.net/img/2020/hagl-put-text-gh.png)\n\n### Blit a bitmap\n\nBlit copies a [bitmap](https://github.com/tuupola/hagl/blob/master/bitmap.c) to the screen. This example uses a glyph bitmap which is extracted from a font.\n\n```c\nhagl_bitmap_t bitmap;\nbitmap.buffer = (uint8_t *) malloc(6 * 9 * sizeof(hagl_color_t));\n\nfor (uint16_t i = 1; i \u003c 20000; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    hagl_color_t color = rand() % 0xffff;\n    uint16_t code = rand() % 0xffff;\n    hagl_get_glyph(display, code, color, \u0026bitmap, font6x9);\n\n    /* These two are aliases. */\n    hagl_blit(display, x0, y0, \u0026bitmap);\n    hagl_blit_xy(display, x0, y0, \u0026bitmap);\n}\n```\n\n![Random blits](https://appelsiini.net/img/2020/hagl-blit.png)\n\n### Blit a bitmap scaled up or down\n\nScale blit copies and scales a [bitmap](https://github.com/tuupola/hagl/blob/master/bitmap.c) to the surface. This example uses a glyph bitmap which is extracted from a font.\n\n```c\nhagl_bitmap_t bitmap;\nbitmap.buffer = (uint8_t *) malloc(6 * 9 * sizeof(hagl_color_t));\n\nfor (uint16_t i = 1; i \u003c 20000; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    hagl_color_t color = rand() % 0xffff;\n    uint16_t code = rand() % 0xffff;\n    hagl_get_glyph(display, code, color, \u0026bitmap, font6x9);\n\n    /* These two examples do the same thing. */\n    hagl_blit_xywh(display, x0, y0, 24, 36, \u0026bitmap);\n    hagl_blit_xyxy(display, x0, y0, x0 + 23, y0 + 35, \u0026bitmap);\n}\n```\n\n![Random blits](https://appelsiini.net/img/2020/hagl-scale-blit.png)\n\n### Clip window\n\nYou can restrict the area of drawing by setting a clip window.\n\n```c\nhagl_set_clip(display, 0, 40, display-\u003ewidth, display-\u003eheight - 40);\n\nfor (uint16_t i = 1; i \u003c 500; i++) {\n    int16_t x0 = rand() % display-\u003ewidth;\n    int16_t y0 = rand() % display-\u003eheight;\n    int16_t radius = rand() % 100;\n    hagl_color_t color = rand() % 0xffff;\n\n    hagl_fill_circle(display, x0, y0, radius, color);\n}\n````\n\n![Clipped windows](https://appelsiini.net/img/2020/hagl-set-clip-window.png)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuupola%2Fhagl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuupola%2Fhagl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuupola%2Fhagl/lists"}