Adafruit GFX Library: the drawing core that deliberately refuses to grow

A base class, not a display driver

The repository description is precise about the role: Adafruit GFX graphics core Arduino library, this is the 'core' class that all our other graphics libraries derive from. The README says the same thing in prose. It is the core graphics library for all Adafruit displays, providing a common set of graphics primitives such as points, lines and circles, and it needs to be paired with a hardware-specific library for each display device in order to handle the lower-level functions.

That pairing requirement is the first thing to understand about the architecture. GFX knows how to draw a filled circle; it does not know how to push pixels over SPI or I2C to a particular controller. `Adafruit_SPITFT.cpp` and `Adafruit_SPITFT.h` in the tree are part of that bridge, along with `Adafruit_SPITFT_Macros.h`, and the README separately instructs you to install the latest Adafruit BusIO library, either through the library manager search or by hand from the Adafruit_BusIO repository.

The other core files follow the same pattern. `Adafruit_GFX.cpp` and `Adafruit_GFX.h` are the library itself, `gfxfont.h` defines the GFXfont struct used by the newer proportional fonts, `glcdfont.c` holds the classic fixed-space font, and `Adafruit_GrayOLED.cpp` is a concrete subclass that lives in the same repository. Written by Limor Fried and released under the BSD license, the header text also carries a redistribution requirement: all text above must be included in any redistribution.

The roadmap is a list of things the project will not accept

Most READMEs have a features section. This one has a roadmap that reads as a rejection notice, and it is the most genuinely useful document in the repository for anyone about to open a pull request.

The framing is the PRIME DIRECTIVE, which the README states as maintaining backward compatibility with existing Arduino sketches, with the explanation that many sketches are hosted elsewhere and do not track changes here, some are in print and can never be changed. The consequence is admitted outright: this library has grown organically over time, sometimes the maintainers paint themselves into a design corner, and they have to live with it or add progressively more ungainly workarounds.

The list of pull requests that will not be merged is specific. Additional or incompatible font formats, because there are already two formats and the code is already bloaty there, which also creates liabilities for tools and documentation. Additional or incompatible bitmap formats, for similar reasons, since it is getting messy. Adding background color to custom fonts to erase prior screen contents, because the only acceptable methods are clearing the area with a filled rect, or drawing text into a GFXcanvas1 and copying to the screen with drawBitmap() with a background color, to avoid flicker. The reasoning is given directly: glyphs can overlap.

Scrolling, whether hardware or software based, is refused because such implementations tend to rely on hardware-specific features that are not universally available, read access to the screen framebuffer, or the addition of virtual functions in GFX which would then have to be added in every subclass, of which there are many. The README's conclusion is that the GFX API is largely set at this point and this is a limitation they live with now. Contributors who must have one of these features are pointed at forking and keeping in sync with upstream.

Fonts are the subsystem that keeps getting new tooling

Where the API is closed, the tooling keeps improving. The README's useful resources section describes four separate tools, which tells you that font handling is the part of the library with the most active community around it.

The `Fonts/` folder contains bitmap fonts for use with recent, meaning 1.1 and later, Adafruit_GFX. To use one in a sketch you include the corresponding .h file and pass the address of the GFXfont struct to setFont(), and passing NULL reverts to the classic fixed-space bitmap font. That two-font model is the reason the roadmap refuses new formats, and the source of the bloat complaint.

The `fontconvert/` folder is a command-line tool for converting TTF fonts to Adafruit GFX header format, and it is the deepest toolchain in the repository, the only subdirectory that looks like a standalone program rather than part of the library. On top of it there is a GFX Font Customiser tool with both a web version and a source repository, which exists to customize or correct the output from fontconvert and to create fonts with only a subset of characters to optimize size. The subsetting point is the practical one for embedded work, where flash is the constraint.

Two older paths round it out. Image2Code is described as a handy Java GUI utility to convert a BMP file into the array code necessary to display the image with the drawBitmap function. The drawXBitmap function pairs with the GIMP photo editor: save a .xbm file and use the array saved in the file to draw a bitmap. Neither is maintained by this repository any more, but both remain the documented route for people who do not want to write a font or bitmap generator.

Release history that is all small additions and one formatting pass

The three most recent releases are short enough to read in a minute, and together they describe how this project actually changes. Version 1.12.6 published on 2026-04-09 added drawRotatedRect and fillRotatedRect methods in pull request 508. Version 1.12.5 published on 2026-03-03 applied clang-format for consistent code style in pull request 505. Version 1.12.4 published on 2025-11-11 corrected the circle method docs, also by BillMerryman, in pull request 487, and that same pull request is credited as the author's first contribution.

Two observations follow. First, a new drawing primitive is still a normal, accepted pull request, so the prime directive constrains formats and plumbing rather than the vocabulary of shapes. Second, the formatting pass in 1.12.5 is exactly what the roadmap anticipates when it says not to reformat code for the sake of reformatting code, because the resulting large visual diff makes it impossible to untangle actual bug fixes from merely rearranged lines, and clang-format will be the final arbiter. The 1.12.5 release is the maintainers doing to themselves the reformat they ask contributors not to do by hand.

The repository's last push was 2026-04-09, the same date as the 1.12.6 tag, and the branch is `master` rather than the `main` that newer GitHub tooling defaults to. It is not archived, it has 2843 stars and 1670 forks, and the single topic is `arduino-library`. The fork count is high relative to the star count, which is roughly what you would expect for a dependency that most users never star directly.

Two build systems, a CMake file, and a component manifest

The tree lists the build entry points a C library needs to serve several Arduino toolchains. There is `CMakeLists.txt` at the root, `component.mk` for the ESP-IDF component system, and `library.properties`, the manifest the Arduino Library Manager reads for name, version and dependencies. A `.clang-format` sits at the root, which is what the 1.12.5 release applied across the codebase, and `.gitignore` is present as expected.

The `examples/` directory is where a first-time user should look, and the repository ships exactly two. `examples/GFXcanvas/` is the one that matters conceptually, because GFXcanvas is the offscreen drawing surface the README names as the flicker-free way to get a background color behind text: draw into a canvas, then copy to the screen with drawBitmap() using a background color. That is the documented answer to a problem the library refuses to solve inside its font path. `examples/mock_ili9341/` is the other, a mocked ILI9341 display, which is the fastest way to see the real call sequence a hardware library follows without wiring a panel.

Neither example is a full drawing demo in the usual sense. That is consistent with the library's position: GFX supplies primitives, and the display-specific library supplies the transport. Someone wanting a working sketch needs GFX plus a driver library plus BusIO, and the README's installation section is explicit about that dependency rather than assuming it.

Why the rejection list is good engineering documentation

It is tempting to read a list of refused features as gatekeeping. Read alongside the stated reason, though, it is unusually honest about the costs of an API that thousands of sketches depend on, many of which the authors cannot edit.

The two costs named are concrete. Font formats multiply liabilities for tools and documentation, and bitmap formats are described as getting messy. Both are the accumulation of small reasonable additions that turn a small library into a bloaty one. The background color refusal is the sharpest example, because it names the exact alternative twice, once as a filled rect and once as a canvas copy, and the alternative is better in the general case because glyphs can overlap.

The scrolling refusal explains the architectural cost most plainly. Software scrolling needs read access to a framebuffer that most panels do not expose, and hardware scrolling needs features that are not universally available. Both would require new virtual functions in GFX, and those would have to be implemented in every subclass. With a base class that many display libraries derive from, that is a permanent tax on every future driver, so the decision to live with the limitation is the cheap option.

The last entry is the one that keeps tone honest: please no more pentagram-drawing PRs. Any oddly-specific drawing functions can go in your own code and aren't helpful in a library context. A project that will tell you not to send it another pentagram function has decided what it is for, and the rest of the roadmap follows from that.

Editorial conclusion

Adafruit GFX is worth understanding as a case study in constraint rather than as a general purpose graphics library. It draws points, lines, circles, rectangles, bitmaps, and text with a fixed font pipeline, it needs a paired hardware library to talk to any actual panel, and it has no scrolling because scrolling would require virtual functions in every subclass. The `Fonts/` directory and the `fontconvert/` tool are where the real utility lives, and `Adafruit_SPITFT` is where the modern SPI path sits. Version 1.12.6 shipped on 2026-04-09 adding rotated rectangle methods, so the file layout is current, while the roadmap says the API surface itself is settled. Start with `examples/GFXcanvas` if you want to draw without hardware, then `examples/mock_ili9341` if you want the real call sequence with a fake transport.

Frequently asked questions

Official sources

1. adafruit/Adafruit-GFX-Library on GitHub
2. Issues
3. Project website
4. README
5. Releases