Adafruit GFX: the drawing calls behind every Adafruit display
Adafruit GFX is not a display driver on its own. It is the layer the Adafruit display libraries (SSD1306, SH110X, ILI9341, ST7735, ST7789, PCD8544 and the rest) are built on: each driver says how to light one pixel, and GFX supplies everything else, from lines and filled circles to text, custom fonts, bitmaps and screen rotation. Learn its calls once and they work on a monochrome OLED and a color TFT alike.
Built in on Mokxi: #include <Adafruit_GFX.h> and it builds, with nothing to install. Free, and no account needed.
What Adafruit GFX Library does
Coordinates start at the top left corner, x to the right and y down. Colors are whatever the display understands: on a one-color OLED they are on, off or inverse, and on a color TFT they are 16-bit RGB565 values, which a driver builds for you with color565(r, g, b).
The detail that catches people is text placement. With the built-in font, setCursor() names the top left of the first character. With a custom GFXfont loaded by setFont(), it names the baseline, so text placed at y = 0 is drawn almost entirely above the screen and vanishes.
| Library Manager name | Adafruit GFX Library |
|---|---|
| Author | Adafruit |
| Include | #include <Adafruit_GFX.h>#include <gfxfont.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Runs, with a gap the note below names. |
| Parts it drives | OLED display, 128x64, TFT display, 240x320 |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <Adafruit_GFX.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "Adafruit GFX Library" by Adafruit from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add Adafruit GFX Library to lib_deps in PlatformIO. Mokxi follows the calls of release 1.11.11, so a sketch written here builds there too.
What to know in the simulator: The Fonts/ headers (FreeSans9pt7b and the rest) draw Mokxi鈥檚 own characters at each font鈥檚 size, not the GNU FreeFont typefaces; a fontconvert font of the sketch鈥檚 own draws as upstream. Characters below 32 and above 126 draw blank.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
display.setRotation(1)
Turns the coordinate system in steps of 90 degrees (0 to 3). width() and height() swap to match, so code that reads them keeps working in landscape.
display.fillScreen(0)
Fills the whole screen with one color. On a TFT that is the slowest call there is, so clear only what changed when you can.
display.drawLine(x0, y0, x1, y1, color)
Draws a straight line between two points. drawFastHLine() and drawFastVLine() are quicker for lines that are flat or upright.
display.fillRoundRect(x, y, w, h, r, color)
A filled rectangle with corners of radius r, the usual shape for a button. drawRect(), fillRect(), drawRoundRect() and drawTriangle() are its relatives.
display.drawCircle(x, y, r, color)
An outlined circle around the center point; fillCircle() draws a solid one and drawEllipse() an oval.
display.setFont(&FreeSans9pt7b)
Switches print() to a GFXfont from the Fonts folder (include its header first). setFont() with no argument goes back to the built-in 6 by 8 font.
#include <Fonts/FreeSans9pt7b.h>
display.setFont(&FreeSans9pt7b);
display.setCursor(0, 20); // the baseline, not the top
display.print("Hello");display.getTextBounds("Hello", 0, 20, &x1, &y1, &w, &h)
Works out the box a string would cover without drawing it, which is how you center text: subtract w / 2 from the middle of the screen.
display.drawBitmap(x, y, icon, 16, 16, color)
Draws a one-bit picture from a byte array. drawRGBBitmap() takes an array of RGB565 pixels for a color screen.
GFXcanvas1 canvas(128, 32)
An off-screen drawing surface in RAM with every GFX call. Draw a frame into it, then copy it out with drawBitmap(x, y, canvas.getBuffer(), 128, 32, color) to avoid flicker.
Example: Grove OLED
On the Arduino Mega 2560 R3. It runs in the browser exactly as printed.
// Grove OLED: the 1.12 inch 128x128 OLED on an SH1107, drawn with
// Adafruit's SH110X library on a Mega.
//
// OLED SDA -> 20 (SDA) SCL -> 21 (SCL) VCC -> 5 V GND -> GND
//
// The library keeps the whole picture in RAM, one bit a pixel: 128 x 128 / 8
// is 2048 bytes, which is all of an Uno's RAM and a quarter of a Mega's, so
// this one runs on the Mega. display() sends it as sixteen pages of 128
// bytes, each with its page address and column 0 first.
//
// A ball bounces round the square, and the page count of each frame is
// printed: only the pages that changed are sent.
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SH110X.h>
Adafruit_SH1107 display(128, 128, &Wire);
int x = 20, y = 30, dx = 3, dy = 2;
void setup() {
Serial.begin(9600);
if (!display.begin(0x3C, true)) {
Serial.println("SH1107 not found");
while (1) {
}
}
display.clearDisplay();
display.setTextSize(1);
display.setTextColor(SH110X_WHITE);
display.setCursor(16, 4);
display.print("Grove OLED 1.12");
display.drawRect(0, 16, 128, 112, SH110X_WHITE);
display.display();
Serial.println("Grove OLED ready");
}
void loop() {
display.fillCircle(x, y, 5, SH110X_BLACK);
x += dx;
y += dy;
if (x < 7 || x > 120) dx = -dx;
if (y < 23 || y > 120) dy = -dy;
display.fillCircle(x, y, 5, SH110X_WHITE);
display.display();
delay(40);
}Open it in the editor, wired and ready to run 路 Grove OLED: the project page
Common errors and how to fix them
fatal error: Adafruit_I2CDevice.h: No such file or directory
Since version 1.10, Adafruit GFX depends on Adafruit BusIO. Install it from the Library Manager (choose Install all when it asks about dependencies), then compile again.
Text with a custom font is cut off or missing at the top of the screen
A GFXfont is drawn from its baseline. Move the cursor down by about the font height, for example setCursor(0, 14) for a 9 point font, or measure it with getTextBounds().
New numbers draw on top of old ones and turn into a blur
Drawing never erases. With the built-in font, setTextColor(foreground, background) paints the whole character cell. Custom fonts draw no background, so fillRect() over the old value first.
Questions and answers
Are the Fonts folder typefaces the real FreeSans and FreeMono on Mokxi?
No. The font headers build and set the size, but on Mokxi they draw Mokxi鈥檚 own characters scaled to that size, so text lands where your sketch puts it in a different typeface. A font you made yourself with fontconvert is drawn from its own bitmaps.
Projects that use Adafruit GFX Library
Built-in projects that include it. Each page has the full sketch and opens in the editor, already wired.
Try Adafruit GFX Library without installing anything
Open the example, change the sketch, and keep your version in a free account.