Skip to content

gfx_compat.md

Latest commit

 

History

History
98 lines (77 loc) · 4.01 KB

gfx_compat.md

File metadata and controls

98 lines (77 loc) · 4.01 KB
Raw

Adafruit_GFX-compatible API (GfxCompat)

GfxCompat is a thin, header-only adapter that exposes the familiar Adafruit_GFX drawing API on top of any lcdgfx display or canvas — with no external Adafruit_GFX library required. It lets existing Adafruit GFX sketches run on every display lcdgfx supports (OLED and colour TFT) while keeping lcdgfx's tiny footprint.

Header: src/canvas/gfx_compat.h (included by lcdgfx.h).

Quick start

#include "lcdgfx.h"

DisplaySSD1306_128x64_I2C display(-1);

// Wrap the display. The template argument is just the display type.
GfxCompat<DisplaySSD1306_128x64_I2C> gfx(display);
// or, letting the type be deduced:
//   auto gfx = makeGfxCompat(display);

void setup()
{
    display.begin();                 // display is still initialised natively
    gfx.fillScreen(0);               // clear (0 = off on monochrome)
    gfx.drawRect(0, 0, gfx.width(), gfx.height(), 1);
    gfx.fillCircle(96, 32, 12, 1);
    gfx.setTextColor(1);
    gfx.setCursor(4, 8);
    gfx.print("Adafruit GFX on lcdgfx");
}

GfxCompat holds a reference to the display, so keep both objects in the same scope.

Colour convention

Colour is passed through exactly as in Adafruit_GFX:

  • Monochrome displays: 0 = off, any non-zero = on. GfxCompat maps this to lcdgfx's internal 0x0000/0xFFFF mask automatically (the branch folds away at compile time — no runtime cost).
  • Colour displays: pass an RGB332 / RGB565 value, e.g. RGB_COLOR16(255, 0, 0).

Supported API

Category Methods
Geometry drawPixel, drawFastHLine, drawFastVLine, drawLine, drawRect, fillRect, fillScreen, drawCircle, fillCircle, drawTriangle, fillTriangle, drawRoundRect, fillRoundRect
Bitmaps drawBitmap (1-bit, foreground colour)
Text setCursor, setTextColor (fg / fg+bg), setTextSize, write, print (const char*, char, int, long), println, setFont(const GFXfont*)
Screen width, height, setRotation, getRotation
Adafruit transaction API startWrite, writePixel, endWrite (no-ops / forwarders)
Escape hatch display() returns the wrapped lcdgfx object for native calls

Custom fonts (GFXfont)

GfxCompat accepts Adafruit GFXfont structures produced by Adafruit's fontconvert tool. The GFXfont / GFXglyph types are defined in gfx_compat.h and are binary-compatible with Adafruit's gfxfont.h (guarded by _GFXFONT_H_, so including the real Adafruit_GFX alongside is safe).

#include "FreeSans9pt7b.h"   // generated by Adafruit fontconvert

gfx.setFont(&FreeSans9pt7b);
gfx.setTextColor(1);
gfx.setCursor(2, 20);
gfx.print("Hello");
gfx.setFont(nullptr);        // revert to the display's built-in fixed font

Glyphs are repacked into lcdgfx's native column/page format and drawn with a single drawBitmap1 call, so custom fonts render correctly on paged monochrome OLEDs as well as colour panels. Fonts stored in PROGMEM (AVR) are handled transparently.

Notes and limitations

  • Text scaling (setTextSize > 1) is accepted for source compatibility but not applied — lcdgfx uses fixed-cell fonts; text renders at size 1.
  • Rotation is stored for compatibility; configure actual rotation through the underlying display's own API.
  • fillTriangle fills by vertical spans (one write per column) rather than Adafruit's horizontal scanlines. This is intentional: on bufferless paged monochrome displays a horizontal fill would clobber earlier rows sharing an 8-pixel page byte. The visual result matches on colour displays.
  • Very large custom glyphs (width * ceil(height/8) > 128 bytes) are skipped to bound stack usage on small MCUs.
  • For lowest footprint and full feature access, prefer lcdgfx's native API; GfxCompat is aimed at porting existing Adafruit GFX code.

See the runnable example: examples/direct_draw/gfx_compat.