Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Marcussacapuces91/doc-TFT_eSPI/llms.txt

Use this file to discover all available pages before exploring further.

TFT_eSPI includes a family of anti-aliased (“smooth”) drawing primitives that blend glyph edges against the background color rather than painting hard pixel borders. The result looks noticeably cleaner on small, high-pixel-density panels where aliasing artifacts are most visible. Every smooth function accepts a bg_color parameter that controls what color edge pixels are blended toward. When bg_color is omitted (or set to the sentinel value 0x00FFFFFF), the library reads the actual background pixel directly from the display — convenient but slower. Passing an explicit bg_color avoids that read and is always the faster option.
Anti-aliased drawing is more CPU-intensive than plain drawing. For small decorative elements such as gauge needles, dial rings, or indicator dots it is an excellent trade-off. For full-screen animations prefer the non-smooth variants.

​
The bg_color Sentinel

The default value 0x00FFFFFF is used as a sentinel meaning “read the background from the display”. Any other 24-bit value is treated as an explicit background color and skips the pixel read. 
// Let the library read the display background automatically
tft.drawSpot(60.0, 60.0, 8.0, TFT_RED);

// Provide an explicit background to avoid the read (faster)
tft.drawSpot(60.0, 60.0, 8.0, TFT_RED, TFT_BLACK);

​
Spots (Anti-Aliased Filled Circles)

​
drawSpot

Draw a small anti-aliased filled circle (a “spot”) at a sub-pixel floating-point position. Internally uses drawWideLine with zero length, so it inherits rounded ends naturally. 
void drawSpot(float ax, float ay, float r, uint32_t fg_color, uint32_t bg_color = 0x00FFFFFF);
​
ax
float
required
Sub-pixel X coordinate of the center.
​
ay
float
required
Sub-pixel Y coordinate of the center.
​
r
float
required
Radius in pixels (floating point for sub-pixel precision).
​
fg_color
uint32_t
required
Foreground fill color.
​
bg_color
uint32_t
Background blend color. Defaults to 0x00FFFFFF (read from display).
drawSpot is maths-intensive. It is designed for small indicator dots, not large filled circles. For large filled circles use fillSmoothCircle instead.
// Draw a series of indicator dots along a line
for (int i = 0; i < 5; i++) {
  tft.drawSpot(20.0 + i * 40.0, 60.0, 6.0, TFT_CYAN, TFT_BLACK);
}

​
Wide and Wedge Lines

​
drawWideLine

Draw an anti-aliased line with a constant width wd at both ends, with radiused caps. 
void drawWideLine(float ax, float ay, float bx, float by,
                  float wd,
                  uint32_t fg_color, uint32_t bg_color = 0x00FFFFFF);
​
ax, ay
float
required
Start point (sub-pixel precision).
​
bx, by
float
required
End point (sub-pixel precision).
​
wd
float
required
Line width in pixels at both ends.
​
fg_color
uint32_t
required
Line color.
​
bg_color
uint32_t
Background blend color. Defaults to 0x00FFFFFF.
// Draw a 4-pixel-wide anti-aliased diagonal line
tft.drawWideLine(10.0, 10.0, 200.0, 150.0, 4.0, TFT_WHITE, TFT_BLACK);

​
drawWedgeLine

Draw an anti-aliased line that tapers: aw sets the radius (half-width) at the start point and bw sets it at the end. This creates a wedge or tapered stroke, ideal for gauge needles and arrows. 
void drawWedgeLine(float ax, float ay, float bx, float by,
                   float aw, float bw,
                   uint32_t fg_color, uint32_t bg_color = 0x00FFFFFF);
​
ax, ay
float
required
Start point.
​
bx, by
float
required
End point.
​
aw
float
required
Half-width (radius) at the start.
​
bw
float
required
Half-width (radius) at the end.
​
fg_color
uint32_t
required
Line color.
​
bg_color
uint32_t
Background blend color. Defaults to 0x00FFFFFF.
// Tapered needle: 4 px wide at base, pointed tip (1 px) at end
tft.drawWedgeLine(120.0, 120.0, 120.0, 30.0, 4.0, 1.0, TFT_RED, TFT_BLACK);

​
Arcs

​
drawSmoothArc

Draw an anti-aliased arc segment. The arc is defined by an outer radius r and an inner radius ir, making it a thick annular sector. Arc thickness = r - ir + 1. Angle 0 is at the 6 o’clock position and increases clockwise (90° = 9 o’clock, 180° = 12 o’clock, 270° = 3 o’clock). Arcs always draw clockwise from startAngle to endAngle; the start may be numerically larger than the end to wrap around. 
void drawSmoothArc(int32_t x,    int32_t y,
                   int32_t r,    int32_t ir,
                   uint32_t startAngle, uint32_t endAngle,
                   uint32_t fg_color,   uint32_t bg_color,
                   bool roundEnds = false);
​
x, y
int32_t
required
Center coordinates.
​
r
int32_t
required
Outer radius in pixels.
​
ir
int32_t
required
Inner radius in pixels. Arc thickness = r - ir + 1.
​
startAngle
uint32_t
required
Start angle in degrees [0..360].
​
endAngle
uint32_t
required
End angle in degrees [0..360].
​
fg_color
uint32_t
required
Arc foreground color, anti-aliased against bg_color at edges.
​
bg_color
uint32_t
required
Background blend color.
​
roundEnds
bool
Round the arc endpoints. Defaults to false.

​
drawArc

Identical to drawSmoothArc except the arc ends are not anti-aliased, and side anti-aliasing can be disabled. This is useful for drawing segmented arcs where clean joints between adjacent segments are required. 
void drawArc(int32_t x,    int32_t y,
             int32_t r,    int32_t ir,
             uint32_t startAngle, uint32_t endAngle,
             uint32_t fg_color,   uint32_t bg_color,
             bool smoothArc = true);
​
smoothArc
bool
When true (default), sides are anti-aliased. Set to false to disable all anti-aliasing for crisp segmented joins.
// Full ring (0 to 360) with anti-aliased sides
tft.drawArc(160, 120, 80, 60, 0, 360, TFT_CYAN, TFT_BLACK);

// Segmented arc, no AA on ends or sides
tft.drawArc(160, 120, 80, 60,   0,  60, TFT_RED,   TFT_BLACK, false);
tft.drawArc(160, 120, 80, 60,  60, 120, TFT_GREEN, TFT_BLACK, false);
tft.drawArc(160, 120, 80, 60, 120, 180, TFT_BLUE,  TFT_BLACK, false);

​
Smooth Circles

​
drawSmoothCircle

Draw an anti-aliased circle outline. The rendered line is 3 pixels wide to reduce the “braiding” artifact that appears with 1-pixel anti-aliased circles. 
void drawSmoothCircle(int32_t x, int32_t y, int32_t r,
                      uint32_t fg_color, uint32_t bg_color);
​
x, y
int32_t
required
Center coordinates.
​
r
int32_t
required
Radius. Inner AA zone at r-1, outer AA zone at r+1.
​
fg_color
uint32_t
required
Circle outline color.
​
bg_color
uint32_t
required
Background blend color.

​
fillSmoothCircle

Draw an anti-aliased filled circle, blending the edge pixels against bg_color. 
void fillSmoothCircle(int32_t x, int32_t y, int32_t r,
                      uint32_t color, uint32_t bg_color = 0x00FFFFFF);
​
x, y
int32_t
required
Center coordinates.
​
r
int32_t
required
Radius in pixels.
​
color
uint32_t
required
Fill color.
​
bg_color
uint32_t
Background blend color. Defaults to 0x00FFFFFF.
tft.drawSmoothCircle(120, 120, 50, TFT_WHITE, TFT_BLACK);
tft.fillSmoothCircle(120, 120, 50, TFT_CYAN,  TFT_BLACK);

​
Smooth Rounded Rectangles

​
drawSmoothRoundRect

Draw an anti-aliased rounded rectangle outline. The corner arcs are defined by an outer radius r and an inner radius ir; arc thickness = r - ir + 1. A bitmask quadrants lets you draw only selected corners. 
void drawSmoothRoundRect(int32_t x, int32_t y,
                         int32_t r,  int32_t ir,
                         int32_t w,  int32_t h,
                         uint32_t fg_color,
                         uint32_t bg_color = 0x00FFFFFF,
                         uint8_t  quadrants = 0xF);
​
x, y
int32_t
required
Top-left corner of the bounding box.
​
r
int32_t
required
Outer corner radius.
​
ir
int32_t
required
Inner corner radius. If w and h are both 0, a circle is drawn.
​
w, h
int32_t
required
Width and height of the bounding box.
​
fg_color
uint32_t
required
Foreground (outline) color.
​
bg_color
uint32_t
Background blend color. Defaults to 0x00FFFFFF.
​
quadrants
uint8_t
Bitmask selecting which corners to draw (default 0xF = all four). Bit layout:
LeftRight
Top0x10x2
Bottom0x80x4

​
fillSmoothRoundRect

Draw an anti-aliased filled rounded rectangle. 
void fillSmoothRoundRect(int32_t x, int32_t y,
                         int32_t w, int32_t h,
                         int32_t radius,
                         uint32_t color,
                         uint32_t bg_color = 0x00FFFFFF);
​
x, y
int32_t
required
Top-left corner.
​
w, h
int32_t
required
Width and height.
​
radius
int32_t
required
Corner radius.
​
color
uint32_t
required
Fill color.
​
bg_color
uint32_t
Background blend color. Defaults to 0x00FFFFFF.
tft.drawSmoothRoundRect(10, 10, 12, 8, 100, 60, TFT_WHITE, TFT_BLACK);
tft.fillSmoothRoundRect(10, 80, 100, 60, 12, TFT_NAVY, TFT_BLACK);

​
Practical Example — Gauge / Dial

The sketch below builds a simple gauge face with a colored arc track, a background ring, and a tapered needle using drawSmoothArc and drawWedgeLine. 
#include <TFT_eSPI.h>
#include <math.h>

TFT_eSPI tft = TFT_eSPI();

// Display a gauge value 0..100 on a dial centered at (cx, cy)
void drawGauge(int cx, int cy, int value) {
  const int   outerR  = 90;
  const int   innerR  = 70;
  const float bgColor = TFT_BLACK;

  // ── Background arc (full track, dark grey) ─────────────────────────────
  tft.drawSmoothArc(cx, cy, outerR, innerR,
                    0, 360,          // full circle
                    0x4208,          // dark grey
                    TFT_BLACK);

  // ── Value arc (colored segment, 0 = 6 o'clock, sweeping clockwise) ─────
  // Map 0..100 to 0..360 degrees
  uint32_t sweep = map(value, 0, 100, 0, 360);
  uint32_t arcColor = (value < 33) ? TFT_GREEN
                    : (value < 66) ? TFT_YELLOW
                                   : TFT_RED;

  if (sweep > 0) {
    tft.drawSmoothArc(cx, cy, outerR, innerR,
                      0, sweep,
                      arcColor,
                      TFT_BLACK);
  }

  // ── Needle ─────────────────────────────────────────────────────────────
  // Angle in degrees from 6 o'clock, clockwise.
  // Convert to radians; 0° = downward = π/2 in standard maths.
  float angleDeg = (float)sweep - 90.0f;   // shift to 12 o'clock = 0°
  float angleRad = angleDeg * (float)M_PI / 180.0f;

  float needleLen = 55.0f;
  float tipX  = cx + needleLen * cos(angleRad);
  float tipY  = cy + needleLen * sin(angleRad);

  // Erase old needle by drawing over with background color, then redraw
  tft.drawWedgeLine((float)cx, (float)cy, tipX, tipY,
                    5.0f, 1.0f,
                    TFT_WHITE, TFT_BLACK);

  // Center hub
  tft.fillSmoothCircle(cx, cy, 6, TFT_WHITE, TFT_BLACK);

  // ── Value label ─────────────────────────────────────────────────────────
  tft.setTextDatum(MC_DATUM);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextPadding(tft.textWidth("100", 4));
  tft.drawNumber(value, cx, cy + 40, 4);
}

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);

  // Draw a smooth bezel
  tft.drawSmoothCircle(160, 120, 95, 0x7BEF, TFT_BLACK);  // light grey ring
  tft.fillSmoothRoundRect(120, 205, 80, 24, 8, 0x2104, TFT_BLACK);

  // Animate the gauge from 0 to 80
  for (int v = 0; v <= 80; v += 2) {
    drawGauge(160, 120, v);
    delay(40);
  }
}

void loop() {}

Shape Primitives

Plain (non-anti-aliased) drawing functions for pixels, lines, and shapes.

Bitmaps and Images

Push color pixel arrays and PROGMEM bitmaps to the display.

Build docs developers (and LLMs) love

Get started for freeTalk to us