2020s on Mika Tuupola

Programming the GD32V Longan Nano

Thu, 03 Dec 2020 00:00:00 +0000

RISC-V is gaining traction and some development boards have already popped up. One of them is the widely available Sipeed Longan Nano. Written information is a bit sparse at the moment. Let’s try to fix this with a quick writeup on wiring and programming the board. If you just want to see what the board can do here is a video instead.

Toolchain

The situation with RISC-V toolchain is somewhat confusing. There are RISC-V Software Collaboration, RISC-V Software, RISC-V Microcontroller and RISC-V repositories. Some vendors also provide their own prebuilt binaries but they often seem to be outdated.

Luckily the toolchain is easy to compile by yourself. Only downside is that the toolchain repository is huge and using a shallow copy did not seem to work.

$ git clone --recursive https://github.com/riscv-collab/riscv-gnu-toolchain.git
$ cd riscv-gnu-toolchain

$ mkdir /opt/riscv
$ ./configure --prefix=/opt/riscv --enable-multilib --with-cmodel=medany
$ make -j8
$ make install

Protip! If you also have Kendryte K210 based development boards, you can use the same toolchain if you configure it like this.

$ ./configure --prefix=/opt/riscv --enable-multilib --with-cmodel=medany \
  --with-arch=rv64imafc --with-abi=lp64f

Additionally you need the RISC-V version of OpenOCD. Below example is for Fedora. You might be missing different set of dependencies.

$ sudo dnf install libtool autoconf automake texinfo
$ sudo dnf install libusb-devel

$ git clone --recursive https://github.com/riscv/riscv-openocd.git
$ cd riscv-openocd

$ ./bootstrap nosubmodule
$ ./configure --prefix=/opt/riscv/
$ make -j8
$ make install

If you are using macOS you can also install the toolchain and OpenOCD with Homebrew.

$ brew tap riscv/riscv
$ brew install riscv-tools
$ brew install riscv-openocd

Nuclei SDK

For programming a GD32V series SoC best choice at the moment is the Nuclei SDK. It seems to be well maintained, exceptionally well structured and is quite easy to learn. Developing is done with your favourite text editor.

The SDK supports three different real time operating systems: FreeRTOS, UCOSII and RT-Thread. Since Longan Nano has only 32kB SRAM you might want to stay baremetal instead.

Nuclei SDK does support Longan Nano out of the box. Basic hello world and the Makefile would look like this.

#include <stdio.h>

void main(void)
{
    printf("Hello world\r\n");
}

TARGET = firmware
NUCLEI_SDK_ROOT = ../nuclei-sdk
SRCDIRS = .

include $(NUCLEI_SDK_ROOT)/Build/Makefile.base

You would compile and upload it with the following commands.

$ make SOC=gd32vf103 BOARD=gd32vf103c_longan_nano all
$ make SOC=gd32vf103 BOARD=gd32vf103c_longan_nano upload

The SDK will take care of basic things such use redirecting STDOUT to USART. This is where the Sipeed USB-JTAG/TTL RISC-V Debugger really pays off. In addition to the JTAG interface it also acts as an USB to TTL converter.

$ screen /dev/ttyUSB1 115200

Nuclei SDK Build Time: Nov 14 2020, 23:17:41
Download Mode: FLASHXIP
CPU Frequency 108540000 Hz
Hello world

Uploading with the Sipeed RISC-V debugger

To make both JTAG and serial interface work you need to connect all pins except NC (duh!) between the debugger and Longan Nano. If nitpicking second ground is also optional. Longan Nano RST is pin number 7 on the left side of the USB socket.

Debugger	Longan Nano
GND	GND
RXD	T0
TXD	R0
NC
GND	GND (optional)
TDI	JTDI
RST	RST
TMS	JTMS
TDO	JTDO
TCK	JTCK

When flashing you also need to connect the USB-C socket to provide power. When using Nuclei SDK you can flash the firmware with make.

$ make SOC=gd32vf103 BOARD=gd32vf103c_longan_nano upload

Uploading with the J-Link debugger

Debugger	Longan Nano
VREF	3v3
GND	GND
TDI	JTDI
NRST	RST
TMS	JTMS
TDO	JTDO
TCK	JTCK

You can also use SEGGER J-Link Commander to upload the firmware. The command line utility requires the firmare to be in hex format.

$ riscv64-unknown-elf-objcopy firmware.elf -O ihex firmware.hex

You can connect to Longan Nano’s JTAG interface automatically with the following.

$ JLinkExe -device GD32VF103VBT6 -speed 4000 -if JTAG \
  -jtagconf -1,-1 -autoconnect 1

SEGGER J-Link Commander V6.86e (Compiled Oct 16 2020 18:21:57)
DLL version V6.86e, compiled Oct 16 2020 18:21:45

...

J-Link>

To upload a new firmware manually, first halt the CPU and load the firmware.hex from above. Reset the core and peripherals. Set the program counter to 0x08000000 and finally enable the CPU and exit the command line utility.

J-Link>halt
J-Link>loadfile firmware.hex
J-Link>r
J-Link>setPC 0x08000000
J-Link>go
J-Link>q

If the new firmware does no run automatically you might need to powercycle the board.

While manually poking the internals might be fun it gets bothersome in the long run. You can also put the above commands to an external file and pass it to JLinkExe to do all of the above automatically.

$ cat upload.jlink
halt
loadfile firmware.hex
r
setPC 0x08000000
go
q

$ JLinkExe -device GD32VF103VBT6 -speed 4000 -if JTAG \
  -jtagconf -1,-1 -autoconnect 1 -CommanderScript upload.jlink

Uploading via USB

If you don’t have an external debugger it is also possible to upload via USB. At the time of writing you need to use latest dfu-util built from source.

$ git clone git://git.code.sf.net/p/dfu-util/dfu-util
$ cd dfu-util
$ ./autogen.sh
$ ./configure --prefix=/opt/dfu-util
$ make -j8
$ sudo make install

Then add /opt/dfu-util/bin to your $PATH and you should be able to flash the firmware via USB.

$ make SOC=gd32vf103 BOARD=gd32vf103c_longan_nano bin
$ dfu-util -d 28e9:0189 -a 0 --dfuse-address 0x08000000:leave -D firmware.bin

Before running dfu-util you need to put the board to download mode. Do this by holding down the RESET and BOOT buttons and then release them in the same order.

Uploading via Serial

Finally the GD32V also offers the good old serial bootloader. Although meant to be used with the STM32 family the stm32flash utility seems to work. You also need to add /opt/stm32flash/bin to your $PATH and you are good to go.

$ git clone https://git.code.sf.net/p/stm32flash/code stm32flash
$ cd stm32flash
$ autoreconf -i -v
$ ./configure --prefix=/opt/stm32flash
$ make -j8
$ sudo make install

You also need an USB to TTL converter. I am using TTL-234X-3V3. Note that while signal levels are 3V3 the VCC on this converter is 5V. With this converter VCC cannot be connected to the debug header. Connect it to the 5V pin instead. This will also power up the board.

USB to TTL	Longan Nano
GND	GND
VCC	5V
RXD	T0
TXD	R0

After wiring is correct you can test if the connection works. Go to bootloader mode by first holding down the RESET and BOOT buttons and then release them in same order. When in bootloader mode you can probe the usb device.

$ stm32flash /dev/ttyUSB0 -b 115200

stm32flash 0.5

http://stm32flash.sourceforge.net/

Interface serial_posix: 115200 8E1
GET returns unknown commands (0x 6)
Version      : 0x30
Option 1     : 0x00
Option 2     : 0x00
Device ID    : 0x0410 (STM32F10xxx Medium-density)
- RAM        : 20KiB  (512b reserved by bootloader)
- Flash      : 128KiB (size first sector: 4x1024)
- Option RAM : 16b
- System RAM : 2KiB

While stm32flash utility detects a device in it gets the specs wrong. Probably because officially it does not support the GD32V family. Flashing still works fine though. You can flash both .bin and .hex files.

$ stm32flash -g 0x08000000 -b 115200 -w firmware.bin /dev/ttyUSB0


stm32flash 0.5

http://stm32flash.sourceforge.net/

Using Parser : Raw BINARY
Interface serial_posix: 115200 8E1
GET returns unknown commands (0x 6)
Version      : 0x30
Option 1     : 0x00
Option 2     : 0x00
Device ID    : 0x0410 (STM32F10xxx Medium-density)
- RAM        : 20KiB  (512b reserved by bootloader)
- Flash      : 128KiB (size first sector: 4x1024)
- Option RAM : 16b
- System RAM : 2KiB
Write to memory
Erasing memory
Wrote address 0x08011d30 (100.00%) Done.

Starting execution at address 0x08000000... done.

Hello World on Screen

For graphics programming you could use HAGL. As the name implies HAGL is a hardware agnostic graphics library. To make it work with Longan Nano you also need a HAGL GD32V HAL

$ cd lib
$ git clone https://github.com/tuupola/hagl.git
$ git clone https://github.com/tuupola/hagl_gd32v_mipi.git hagl_hal

Add both dependencies to the project Makefile.

TARGET = firmware
NUCLEI_SDK_ROOT = ../nuclei-sdk
SRCDIRS = . lib/hagl/src lib/hagl_hal/src
INCDIRS = . lib/hagl/include lib/hagl_hal/include

include $(NUCLEI_SDK_ROOT)/Build/Makefile.base

With all this in place you can create a flashing RGB Hello world!

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

void main()
{
    color_t red = hagl_color(255, 0, 0);
    color_t green = hagl_color(0, 255, 0);
    color_t blue = hagl_color(0, 0, 255);

    hagl_init();
    hagl_clear_screen();

    while (1) {
        hagl_put_text(L"Hello world!", 48, 32, red, font6x9);
        delay_1ms(100);

        hagl_put_text(L"Hello world!", 48, 32, green, font6x9);
        delay_1ms(100);

        hagl_put_text(L"Hello world!", 48, 32, blue, font6x9);
        delay_1ms(100);
    };
}

Animations on screen

For testing purpose lets assume we have three functions to initialise, animate and render bouncing balls on the screen.

balls_init();
balls_animate();
balls_render();

You can find the actual implementation in GitHub. With above functions we can implement the main loop.

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

void main()
{
    hagl_init();
    balls_init();

    while (1) {
        balls_animate();
        hagl_clear_screen();
        balls_render();
    };
}

Writing directly to display is fine for unanimated content. However above code will have a horrible flicker. Problem can be fixed by enabling double buffering in hte Makefile.

COMMON_FLAGS += -DHAGL_HAL_USE_DOUBLE_BUFFER

With double buffering enabled we also need to flush the contents from back buffer to display ie. front buffer. Here I also add some delay to slow down the animation.

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

void main()
{
    hagl_init();
    balls_init();

    while (1) {
        balls_animate();
        hagl_clear_screen();
        balls_render();

        hagl_flush();
        delay_1ms(30);
    };
}

This is very naive approach and you need to manually adjust the delay to avoid tearing. It would be better to implement an fps limiter and flush the contents, for example 30 times per second.

Even though the Longan Nano is not the fastest and has only 32kB of memory the Nuclei SDK makes it pleasant to work with. Despite being tiny you can still do interesting stuff such as old school demo effects with it.

Additional reading

Creating a Videoplayer for ESP32

Mon, 25 May 2020 00:00:00 +0000

One of the things which makes embedded programming so interesting is that you are constantly dealing with restricted resources. Playing video files is quite resource heavy. Let’s see how ESP32 can handle this. If you have short attention span here is a video instead.

RAW RGB565

The easiest compression is no compression at all. Embedded displays are often configured to have RGB565 pixel format. This gives a good compromise between number of colors and bytes needed for one frame.

Raw video means each frame is consecutively stored in a file. There is no compression. There is no file header containing meta. Following code reads the first frame of such video.

To keeps the example code simple I am using an SD card helper component to initialise the SD card.

FILE *fp;
const size_t FRAME_SIZE = 320 * 180 * 2;
uint8_t *buffer = malloc(FRAME_SIZE);

sdcard_init();

fp = fopen("/sdcard/video.raw", "rb");
fread(buffer, FRAME_SIZE, 1, fp);
fclose(fp);

All frames can be read in a loop.

FILE *fp;
const size_t FRAME_SIZE = 320 * 180 * 2;
uint8_t *buffer = malloc(FRAME_SIZE);

fp = fopen("/sdcard/video.raw", "rb");

while (fread(buffer, FRAME_SIZE, 1, fp)) {
    printf("Read a frame.\n");
};

fclose(fp);

This is still not interesting since nothing is displayed. You could blit the frame one by one to the display. Better still the buffer could be a pointer directly to the framebuffer or back buffer.

I am using graphics library called HAGL. It gives you a pointer to the back buffer when initialising the display. The back buffer also has to be flushed to the display.

I am also adding an fps counter to see how well our video player is working.

FILE *fp;
const size_t FRAME_SIZE = 320 * 180 * 2;
bitmap_t *hagl;

hagl = hagl_init();
sdcard_init();

fp = fopen("/sdcard/video.raw", "rb");

while (fread(hagl->buffer, FRAME_SIZE, 1, fp)) {
    hagl_flush();
    printf("%.*f FPS\n", 1, fps());
};

fclose(fp);

Avoid the SD card bottleneck

The results are surprising bad. The video plays at only about 6 fps. The culprit seems to be newlibs default buffer size which causes files to be read in 128 byte chunks. Easy fix is to replace fread() with read().

Note that while fread() above returns number of frames read, read() here returns number of bytes read.

FILE *fp;
const size_t FRAME_SIZE = 320 * 180 * 2;
bitmap_t *hagl;

hagl = hagl_init();
sdcard_init();

fp = fopen("/sdcard/video.raw", "rb");

while (read(fileno(fp), hagl->buffer, FRAME_SIZE)) {
    hagl_flush();
    printf("%.*f FPS\n", 1, fps());
};

fclose(fp);

Results are now much better. The raw video can be played at approximately 10 fps. Consecutively calling printf() slows things down. Removing it would allow 12 fps playback. Things can still be sped up by moving the display flushing to second ESP32 core.

That would make the example code too complicated for this article so we are good for now. See the ESP32 videoplayer repository to see how it was done.

First part of this video shows the RGB565 player on a TTGO T4.

Motion JPEG

Motion JPEG or MJPEG is an intraframe video compression format. Each frame is compressed and stored separately as a JPG image. In laymans terms MJPEG is multiple JPG files concatenated into one bigger video file.

Uncompressing JPG images

MJPEG video is just a bunch of JPG files. If the device can uncompress JPG files it should be able to play MJPEG videos. Most embedded libraries I have seen piggypack on the Tiny JPEG Decompressor. It needs to be provided with two functions: one for reading a file and one for outputting the pixels.

Purpose of reader function is to either read bytes into buffer or skip bytes from the file pointer. If buffer is NULL function will fast forward the pointer size bytes.

uint16_t tjpgd_data_reader(JDEC *decoder, uint8_t *buffer, uint16_t size)
{
    FILE *fp = (FILE *)decoder->device;

    if (buffer) {
        /* Read bytes from input stream. */
        return read(fileno(fp), buffer, size);
    } else {
        /* Skip bytes from input stream. */
        if (lseek(fileno(fp), size, SEEK_CUR) > 0) {
            return size;
        }
        /* Seek failed, causes TJPGD to abort. */
        return 0;
    }
}

Writer function receives the uncompressed image in 8x8 blocks. Here I use HAGL provided blit function to blit that block into the display. You could also a putpixel function for the same purpose.

uint16_t tjpgd_data_writer(JDEC* decoder, void* bitmap, JRECT* rectangle)
{
    uint8_t width = (rectangle->right - rectangle->left) + 1;
    uint8_t height = (rectangle->bottom - rectangle->top) + 1;

    /* Create a HAGL bitmap from the uncompressed block. */
    bitmap_t block = {
        .width = width,
        .height = height,
        .depth = DISPLAY_DEPTH,
    };

    bitmap_init(&block, (uint8_t *)bitmap);

    /* Blit the block to the display. */
    hagl_blit(rectangle->left, rectangle->top + 30, &block);

    return 1;
}

Putting things together this is how you would display a JPG image.

uint8_t work[3100];
FILE *fp;
JDEC decoder;
JRESULT result;

sdcard_init();

fp = fopen("/sdcard/image.jpg", "rb");

result = jd_prepare(&decoder, tjpgd_data_reader, work, 3100, fp);
if (JDR_OK == result) {
    jd_decomp(&decoder, tjpgd_data_writer, 0);
};

hagl_flush();
fclose(fp);

Uncompressing MJPEG videos

So in theory to play an MJPEG file we should be able to just open the file and then read the JPG frames one by one.

uint8_t work[3100];
JDEC decoder;
JRESULT result;
FILE *fp;

hagl_init();
sdcard_init();

fp = fopen("/sdcard/video.mjpeg", "rb");

while (1) {
    /* Prepare next frame. */
    result = jd_prepare(&decoder, tjpgd_data_reader, work, 3100, fp);

    if (JDR_OK == result) {
        jd_decomp(&decoder, tjpgd_data_writer, 0);
        /* Frame ready, flush it to the display. */
        hagl_flush();
        printf("%.*f FPS\n", 1, fps());
    } else {
        printf("Prepare failed!\n");
    }
};

fclose(fp);

However there is a problem. It only reads the first frame and then spits out prepare failed errors. The problem here is the tjpgd_data_reader() function. It reads the compressed data in 512 byte blocks. This means most of the time file pointer is advanced past the EOI (end of image) marker into the territory of the next frame.

When reading the next frame file pointer is already past the image header and TJPGD fails to read the image meta. Simple solution here is to rewind the filepointer back to the next byte after EOI marker.

static uint16_t tjpgd_data_reader_new(JDEC *decoder, uint8_t *buffer, uint16_t size)
{
    FILE *fp = (FILE *)decoder->device;
    uint16_t bytes = 0;
    const uint16_t EOI = 0xffd9;
    uint8_t *match;

    if (buffer) {
        /* Read bytes from input stream. */
        bytes = read(fileno(fp), buffer, size);

        /* Search for EOI. */
        match = memmem(buffer, size, &EOI, 2);

        if (match) {
            /* Rewind back to previous EOI + 1. */
            int16_t offset = match - buffer;
            int16_t rewind = offset - size + 1;
            lseek(fileno(fp), rewind, SEEK_CUR);
            bytes += rewind;
        }

        return bytes;
    } else {
        /* Skip bytes from input stream. */
        if (lseek(fileno(fp), size, SEEK_CUR) > 0) {
            return size;
        }
        /* Seek failed, causes TJPGD to abort. */
        return 0;
    }
}

With this fix we now have a working MJPEG player. It is not the fastest. The above code is capable of playing 320x240 video with 6.5 fps. Again offloading display flushing to second ESP32 core would speed things up to 8 fps. See the ESP32 videoplayer repository to see how it was done.

Second part of this video starting at 00:45 shows the MJPEG player on a TTGO T4.

Additional reading

Hardware Agnostic Graphics Library for Embedded

Thu, 16 Apr 2020 00:00:00 +0000

What started as a project to learn C, I have now been using in all my hobby projects. HAGL is a hardware agnostic graphics library for embedded projects. It supports basic geometric primitives, bitmaps, blitting, fixed width fonts and an optional framebuffer.

Yet another graphics library?

Most embedded hobbyist projects do not seem to care about code reuse. Instead there is a graphics library for every different display driver for every different architecture. They all implement the same functions for drawing the graphical primitives This feels wrong. Graphics library should not know anything about the underlying hardware, responsibilities should be separated.

HAGL takes a different approach. It contains code only for drawing the primitives. It can be used with any microcontroller and display driver. It can also be used with normal computers. This is useful for testing your graphics code without need to flash it to the microcontroller.

Hardware abstraction layer

To use Copepod with your microcontroller and display driver you must provide a HAL. The only mandatory function for HAL to provide is for putting a single pixel on the display. Copepod will use the putpixel funtion to draw all the other graphical primitives. For examples of this see libgd HAL and libsdl2 HAL.

For improved speed the HAL can also provide accelerated functions for bitmap blitting and horizontal and vertical lines. See ESP MIPI DCS HAL for an example of a hardware accelerated HAL. This is also the one I use with my ESP32 projects. It supports most of the displays hobbyists currently use.

How fast is it?

Speed mostly depends on two things. Everything is much faster when double buffering is enabled. Also the HAL implementation dictates a lot. I have been testing with the TTGO T-Display, TTGO T4, M5StickC and M5Stack.

NOTE! Links above are affiliate links. If you buy something I will be a happy puppy.

In the below table numbers are operations per second with double buffering. ESP32 is clocked at the default 160MHz. Bigger number is better. T-Display and M5StickC have higher numbers because they have smaller resolution. Smaller resolution means less bytes to push to the display.

	T4	T-Display	M5Stack	M5StickC
hagl_put_pixel()	304400	304585	340850	317094
hagl_draw_line()	10485	14942	12145	31293
hagl_draw_circle()	15784	16430	17730	18928
hagl_fill_circle()	8712	9344	9982	13910
hagl_draw_ellipse()	8187	8642	9168	10019
hagl_fill_ellipse()	3132	3457	3605	5590
hagl_draw_triangle()	3581	5137	4160	11186
hagl_fill_triangle()	1246	1993	1654	6119
hagl_draw_rectangle()	22759	30174	26910	64259
hagl_fill_rectangle()	2191	4849	2487	16146
hagl_draw_rounded_rectangle()	17660	21993	20736	39102
hagl_fill_rounded_rectangle()	2059	4446	2313	13270
hagl_draw_polygon()	2155	3096	2494	6763
hagl_fill_polygon()	692	1081	938	3295
hagl_put_char()	29457	29131	32429	27569
hagl_flush()	32	76	32	96

When double buffering is disabled everything is much slower. On the positive side you save lots of memory.

	T4	T-Display	M5Stack	M5StickC
hagl_put_pixel()	16041	15252	16044	24067
hagl_draw_line()	113	172	112	289
hagl_draw_circle()	148	173	145	230
hagl_fill_circle()	264	278	261	341
hagl_draw_ellipse()	84	103	85	179
hagl_fill_ellipse()	114	128	116	191
hagl_draw_triangle()	37	54	37	114
hagl_fill_triangle()	72	111	72	371
hagl_draw_rectangle()	2378	2481	2374	3482
hagl_fill_rectangle()	91	146	91	454
hagl_draw_rounded_rectangle()	458	535	459	808
hagl_fill_rounded_rectangle()	87	139	79	400
hagl_draw_polygon()	21	33	19	71
hagl_fill_polygon()	43	66	49	228
hagl_put_char)	4957	4264	4440	2474
hagl_flush()	x	x	x	x

You can run the speed tests yourself by checking out the speedtest repository.

Graphical functions

The function calls themselves should be pretty self explanatory. Most of them take coordinates and a RGB565 color. Out of bounds coordinates are clipped to the current display.

Put a pixel

for (uint32_t i = 1; i < 100000; i++) {
    int16_t x0 = rand() % DISPLAY_WIDTH;
    int16_t y0 = rand() % DISPLAY_HEIGHT;
    color_t color = rand() % 0xffff;

    hagl_put_pixel(x0, y0, color);
}

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;
    color_t color = rand() % 0xffff;

    hagl_draw_line(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 width = rand() % (DISPLAY_WIDTH - x0);
    color_t color = rand() % 0xffff;

    hagl_draw_hline(x0, y0, width, 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 height = rand() % (DISPLAY_HEIGHT - y0);
    color_t color = rand() % 0xffff;

    hagl_draw_vline(x0, y0, height, 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;
    color_t color = rand() % 0xffff;

    hagl_draw_circle(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;
    color_t color = rand() % 0xffff;

    hagl_fill_circle(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;
    color_t color = rand() % 0xffff;

    hagl_draw_ellipse(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;
    color_t color = rand() % 0xffff;

    hagl_draw_ellipse(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;
color_t color = rand() % 0xffff;

hagl_draw_triangle(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;
color_t color = rand() % 0xffff;

hagl_fill_triangle(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;
    color_t color = rand() % 0xffff;

    hagl_draw_rectangle(x0, y0, x1, y1, 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;
    color_t color = rand() % 0xffff;

    hagl_fill_rectangle(x0, y0, x1, y1, 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 r = 10
    color_t color = rand() % 0xffff;

    hagl_draw_rounded_rectangle(x0, y0, x1, y1, 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 r = 10
    color_t color = rand() % 0xffff;

    hagl_fill_rounded_rectangle(x0, y0, x1, y1, r, color);
}

Draw a polygon

You can draw polygons with unlimited number of vertices which are passed as an array. Pass the number of vertices as the first argument.

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;
int16_t x3 = rand() % DISPLAY_WIDTH;
int16_t y3 = rand() % DISPLAY_HEIGHT;
int16_t x4 = rand() % DISPLAY_WIDTH;
int16_t y4 = rand() % DISPLAY_HEIGHT;
color_t color = rand() % 0xffff;
int16_t vertices[10] = {x0, y0, x1, y1, x2, y2, x3, y3, x4, y4};

hagl_draw_polygon(5, vertices, color);

Draw a filled polygon

You 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.

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;
int16_t x3 = rand() % DISPLAY_WIDTH;
int16_t y3 = rand() % DISPLAY_HEIGHT;
int16_t x4 = rand() % DISPLAY_WIDTH;
int16_t y4 = rand() % DISPLAY_HEIGHT;
color_t color = rand() % 0xffff;
int16_t vertices[10] = {x0, y0, x1, y1, x2, y2, x3, y3, x4, y4};

hagl_fill_polygon(5, vertices, color);

The library supports Unicode fonts in fontx format. It only includes three fonts by default. You can find more at tuupola/fonts repository.

Put a single char

for (uint16_t i = 1; i < 10000; i++) {
    int16_t x0 = rand() % DISPLAY_WIDTH;
    int16_t y0 = rand() % DISPLAY_HEIGHT;
    color_t color = rand() % 0xffff;
    char ascii = rand() % 127;

    hagl_put_char(ascii, x0, y0, color, font8x8);
}

Put a string

The library supports Unicode fonts in fontx format. It only includes three fonts by default. You can find more at tuupola/fonts repository.

for (uint16_t i = 1; i < 10000; i++) {
    int16_t x0 = rand() % DISPLAY_WIDTH;
    int16_t y0 = rand() % DISPLAY_HEIGHT;
    color_t color = rand() % 0xffff;

    hagl_put_text("YO! MTV raps.", x0, y0, color, font8x8);
}

Additional reading

Efficient Polygon Fill Algorithm With C Code Sample by Darel Rex Finley explains the algorithm I used for drawing the filled polygons.

256-Color VGA Programming in C by David Brackeen is an old tutorial on VGA graphics programming for DOS. Many things can still be applied.

The DIYConsole series by Davide Pesce. Even though written for Arduino the article series a great job explaining many of the aspects required for writing a graphics library.

Lode’s Fire Effect Tutorial by Lode Vandevenne shows how to create the old school fire effect shown in the header image. Code for ESP32 can also be found in GitHub.