truetype2gfx - Converting fonts from TrueType to Adafruit GFX

Demo text

Introducing truetype2gfx

Many Arduino projects and ready-built devices come with a display. And the Adafruit GFX display driver is used by many of them to display variable-width fonts. Some fonts usually are included with the driver, and then there's a complicated procedure for adding your own fonts. It involves compiling tools and a trial-and-error process for figuring out how big the font will turn out on your display.

But now you can skip all that and convert the fonts your Arduino project needs with ease. No need to compile tools, no more guessing how big a font will be. Simply select a FreeFont or upload any TrueType font, select a size, download the include file and you're ready to use the font in your project.

The size thing

Font sizes are given in points, where a point is 1/72 of an inch, describing the actual size on a display. Or that's what it's supposed to mean, but pretty much everyone that uses the Adafruit software keeps the setting of 141 pixels per inch. In the Adafruit software it says:

#define DPI 141 // Approximate res. of Adafruit 2.8" TFT

But since everyone keeps the setting, a certain font at 20 points is going to take up the same number of pixels on a lot of devices. And then there's the different fonts displaying at radically different sizes due to various metrics included in the font. (See here for details.) But I don't have to care about that: when I make gfx fonts and include them on my device, they are the same size as they are on the virtual device on the screen above. (This only works if your screen is 320x240 pixels. If your screen dimensions are different, you can still see the size relative to the FreeFonts of a given size.)

Your own fonts

TrueType fonts are everywhere online. At the time of writing this, you can get loads and loads of pretty TrueType fonts here but you can also pick up fonts at any of these sites. (Beware of malware: do not unpack ".exe archives" or do anything else silly with files downloaded from these sites.)

Using this tool, you can upload and then view and convert up to five fonts (which are only available to you). If you upload a sixth font, the first one disappears. Also note that these fonts will only last as long as your PHP session does, so whenever you come back a day later, your fonts may be gone. It's really only meant to be a short-term buffer.

Example

I found a nice font on this website listed above. It was called "Black Street" and the font file I uploaded was "Black Street.ttf". I fiddled with the size until it filled the display nicely, at 35 points. I then hit the "Get GFX font file" button and my browser downloaded a file called "Black_Street35pt7b.h". I created a new Arduino sketch with the following content:

#include <M5Stack.h>
#include "Black_Street35pt7b.h"

void setup
  m5.begin();
  m5.lcd.fillScreen(TFT_WHITE);
  m5.lcd.setTextColor(TFT_BLACK);
  m5.lcd.setTextDatum(CC_DATUM);
  m5.lcd.setFreeFont(&Black_Street35pt7b);
  m5.lcd.drawString("Testing 123...", 160, 120);
}

void loop() {
}

I then added the "Black_Street35p7b.h" from my "Download" directory as a second tab with "Sketch / Add file..." in the Arduino IDE, ran the program et voila:

(If you do not have an M5Stack but some other device your library will not be called M5Stack.h and your display will not be at "m5.lcd", but you'll figure it out...)

Source code, bug reports, questions, etc..

This tool has a github repository that has the (quick-hack-style) PHP/Javascript code behind all this. And if you have any questions, bug reports or suggestions, simply open a new issue there and I will see what I can do.