TFT_eSPI Shape and Line Outline Drawing API Reference

TFT_eSPI provides a rich set of shape-drawing methods for rendering outlines, lines, curves, and bitmaps to the display. These methods draw the border or path of a shape without filling its interior — for solid fills see the Filling Shapes reference. Several methods have anti-aliased “smooth” variants that blend edges with the background for sub-pixel precision. All coordinate parameters use screen pixels with (0, 0) at the top-left corner of the current rotation.

drawPixel() — Draw a Single Pixel

// Overload 1 – opaque pixel
void drawPixel(int32_t x, int32_t y, uint32_t color)

// Overload 2 – alpha-blended pixel
uint16_t drawPixel(int32_t x, int32_t y, uint32_t color,
                   uint8_t alpha, uint32_t bg_color = 0x00FFFFFF)

Draws a single pixel. The second overload alpha-blends color over bg_color using the given alpha value. If bg_color is omitted (left at 0x00FFFFFF) the background is read directly from the TFT or sprite.

int32_t

Horizontal pixel coordinate.

int32_t

Vertical pixel coordinate.

color

uint32_t

Pixel colour in RGB565 or a TFT_* colour constant.

alpha

uint8_t

Alpha blend value (0 = fully transparent, 255 = fully opaque). Only used by overload 2.

bg_color

uint32_t

Background colour for blending. Default 0x00FFFFFF causes the background to be read from the display. Only used by overload 2.

Returns (overload 2): uint16_t — the resulting RGB565 pixel colour after alpha blending.

tft.drawPixel(10, 10, TFT_RED);                     // opaque red pixel
uint16_t result = tft.drawPixel(20, 20, TFT_BLUE, 128); // 50% blue over display background

drawLine() — Arbitrary Line

void drawLine(int32_t xs, int32_t ys, int32_t xe, int32_t ye, uint32_t color)

Draws a straight line between two points using Bresenham’s algorithm. Fully clips to the viewport.

int32_t

X coordinate of the start point.

int32_t

Y coordinate of the start point.

int32_t

X coordinate of the end point.

int32_t

Y coordinate of the end point.

color

uint32_t

Line colour.

tft.drawLine(0, 0, 239, 319, TFT_GREEN);

drawFastHLine() / drawFastVLine() — Optimized Axis-Aligned Lines

void drawFastHLine(int32_t x, int32_t y, int32_t w, uint32_t color)
void drawFastVLine(int32_t x, int32_t y, int32_t h, uint32_t color)

Hardware-optimized horizontal and vertical line drawing. Significantly faster than drawLine() for axis-aligned lines because a single address-window command covers the entire span.

int32_t

X start coordinate.

int32_t

Y start coordinate.

int32_t

Length in pixels for the horizontal line.

int32_t

Length in pixels for the vertical line.

color

uint32_t

Line colour.

tft.drawFastHLine(10, 60, 200, TFT_WHITE); // horizontal white line
tft.drawFastVLine(120, 0, 240, TFT_CYAN);  // vertical cyan line

drawRect() — Rectangle Outline

void drawRect(int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color)

Draws the outline of an axis-aligned rectangle. The top-left corner is at (x, y).

int32_t

X coordinate of the top-left corner.

int32_t

Y coordinate of the top-left corner.

int32_t

Rectangle width in pixels.

int32_t

Rectangle height in pixels.

color

uint32_t

Border colour.

tft.drawRect(10, 10, 100, 60, TFT_RED);

drawRoundRect() — Rounded Rectangle Outline

void drawRoundRect(int32_t x, int32_t y, int32_t w, int32_t h,
                   int32_t radius, uint32_t color)

Draws the outline of a rectangle with rounded corners.

int32_t

X coordinate of the top-left corner.

int32_t

Y coordinate of the top-left corner.

int32_t

Rectangle width.

int32_t

Rectangle height.

radius

int32_t

Corner arc radius in pixels. Larger values produce more rounded corners.

color

uint32_t

Border colour.

tft.drawRoundRect(20, 20, 80, 50, 8, TFT_BLUE);

drawSmoothRoundRect() — Anti-Aliased Rounded Rectangle

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)

Draws an anti-aliased rounded rectangle arc. The arc thickness is r - ir + 1. If w and h are both 0 a full circle is drawn centred at (x + r, y + r). Omitting bg_color causes the background to be read from the display.

int32_t

X coordinate of the bounding box top-left corner.

int32_t

Y coordinate of the bounding box top-left corner.

int32_t

Outer corner radius.

int32_t

Inner corner radius. Arc thickness = r - ir + 1.

int32_t

Bounding box width (set to 0 for a circle).

int32_t

Bounding box height (set to 0 for a circle).

fg_color

uint32_t

Foreground (arc) colour.

bg_color

uint32_t

Background colour for anti-aliasing. Default 0x00FFFFFF reads from the display.

quadrants

uint8_t

Bitmask selecting which quadrants to draw (default 0xF = all four). Bit layout: top-left=0x1, top-right=0x2, bottom-right=0x4, bottom-left=0x8.

tft.drawSmoothRoundRect(10, 10, 12, 8, 100, 60, TFT_WHITE, TFT_BLACK);

drawCircle() — Circle Outline

void drawCircle(int32_t x, int32_t y, int32_t r, uint32_t color)

Draws a circle outline using the optimized midpoint circle algorithm.

int32_t

X coordinate of the centre.

int32_t

Y coordinate of the centre.

int32_t

Radius in pixels.

color

uint32_t

Outline colour.

tft.drawCircle(120, 120, 50, TFT_WHITE);

drawSmoothCircle() — Anti-Aliased Circle Outline

void drawSmoothCircle(int32_t x, int32_t y, int32_t r,
                      uint32_t fg_color, uint32_t bg_color)

Draws an anti-aliased circle outline. The line is 3 pixels thick to reduce the visible “braiding” artefact of narrow anti-aliased lines; the inner anti-alias zone is at r - 1 and the outer zone at r + 1.

int32_t

X coordinate of the centre.

int32_t

Y coordinate of the centre.

int32_t

Radius in pixels.

fg_color

uint32_t

Foreground (circle) colour.

bg_color

uint32_t

Background colour used for anti-aliasing.

tft.drawSmoothCircle(100, 100, 45, TFT_RED, TFT_BLACK);

drawCircleHelper() — Quadrant Arc Helper

void drawCircleHelper(int32_t x, int32_t y, int32_t r,
                      uint8_t cornername, uint32_t color)

Draws one or more quadrant arcs of a circle. This is a support function used internally by drawRoundRect(). The cornername bitmask selects which quadrants to render: bit 0 = top-left, bit 1 = top-right, bit 2 = bottom-right, bit 3 = bottom-left.

int32_t

X coordinate of the circle centre.

int32_t

Y coordinate of the circle centre.

int32_t

Radius in pixels.

cornername

uint8_t

Bitmask of quadrants to draw (0x1–0xF).

color

uint32_t

Arc colour.

drawEllipse() — Ellipse Outline

void drawEllipse(int16_t x, int16_t y, int32_t rx, int32_t ry, uint16_t color)

Draws an axis-aligned ellipse outline.

int16_t

X coordinate of the centre.

int16_t

Y coordinate of the centre.

int32_t

Horizontal radius (semi-axis along X).

int32_t

Vertical radius (semi-axis along Y).

color

uint16_t

Outline colour.

tft.drawEllipse(120, 120, 60, 30, TFT_YELLOW);

drawTriangle() — Triangle Outline

void drawTriangle(int32_t x1, int32_t y1,
                  int32_t x2, int32_t y2,
                  int32_t x3, int32_t y3,
                  uint32_t color)

Draws the outline of a triangle defined by three arbitrary vertex coordinates.

int32_t

X coordinate of vertex 1.

int32_t

Y coordinate of vertex 1.

int32_t

X coordinate of vertex 2.

int32_t

Y coordinate of vertex 2.

int32_t

X coordinate of vertex 3.

int32_t

Y coordinate of vertex 3.

color

uint32_t

Outline colour.

tft.drawTriangle(60, 10, 120, 110, 10, 110, TFT_YELLOW);

drawArc() — Arc (Configurable Anti-Aliasing)

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)

Draws an arc clockwise from the start angle to the end angle. Angle 0° is at the 6 o’clock position, 90° at 9 o’clock. Arc ends are not anti-aliased, which keeps segment joints clean when building dynamic arc displays. Side anti-aliasing is controlled by smoothArc.

int32_t

X coordinate of the arc centre.

int32_t

Y coordinate of the arc centre.

int32_t

Outer radius of the arc.

int32_t

Inner radius (arc thickness = r - ir + 1).

startAngle

uint32_t

Start angle in degrees (0–360). 0° = 6 o’clock.

endAngle

uint32_t

End angle in degrees (0–360). Arc draws clockwise from start to end.

fg_color

uint32_t

Foreground (arc) colour.

bg_color

uint32_t

Background colour for anti-aliasing.

smoothArc

bool

If true (default), sides are anti-aliased. Set false for hard-edged arc sides.

// Draw a red arc from 12 o'clock (270°→ → 0°) to 3 o'clock (90°)
tft.drawArc(160, 120, 80, 60, 270, 90, TFT_RED, TFT_BLACK);

drawSmoothArc() — Arc with Anti-Aliased Ends

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)

Like drawArc() but the arc ends are also anti-aliased. Optionally rounded end caps can be enabled with roundEnds = true.

int32_t

X coordinate of the arc centre.

int32_t

Y coordinate of the arc centre.

int32_t

Outer arc radius.

int32_t

Inner arc radius.

startAngle

uint32_t

Start angle 0–360° (0 = 6 o’clock).

endAngle

uint32_t

End angle 0–360°.

fg_color

uint32_t

Arc colour.

bg_color

uint32_t

Background colour for end-cap anti-aliasing.

roundEnds

bool

If true, arc ends are rounded. Default false gives straight anti-aliased ends.

tft.drawSmoothArc(160, 120, 80, 65, 0, 270, TFT_CYAN, TFT_BLACK, true);

drawSpot() — Anti-Aliased Filled Circle (Sub-Pixel)

void drawSpot(float ax, float ay, float r,
              uint32_t fg_color, uint32_t bg_color = 0x00FFFFFF)

Draws a small anti-aliased filled circle at floating-point coordinates for sub-pixel positioning accuracy. Internally uses drawWideLine(). This is maths-intensive and intended only for small circles.

float

Floating-point X coordinate of the centre.

float

Floating-point Y coordinate of the centre.

float

Radius in pixels (floating-point).

fg_color

uint32_t

Spot colour.

bg_color

uint32_t

Background colour. Default 0x00FFFFFF reads from the display.

tft.drawSpot(59.5f, 79.5f, 4.0f, TFT_WHITE, TFT_BLACK);

drawSpot() is maths-intensive. Use it only for small radii or infrequent draws.

drawWideLine() — Anti-Aliased Wide Line (Uniform Width)

void drawWideLine(float ax, float ay, float bx, float by,
                  float wd, uint32_t fg_color, uint32_t bg_color = 0x00FFFFFF)

Draws an anti-aliased line with uniform width wd and rounded ends from (ax, ay) to (bx, by).

float

X start coordinate (floating-point).

float

Y start coordinate.

float

X end coordinate.

float

Y end coordinate.

float

Line width in pixels.

fg_color

uint32_t

Line colour.

bg_color

uint32_t

Background colour. Default 0x00FFFFFF reads from the display.

tft.drawWideLine(10.0f, 10.0f, 200.0f, 180.0f, 4.0f, TFT_ORANGE, TFT_BLACK);

drawWedgeLine() — Anti-Aliased Tapered Line

void drawWedgeLine(float ax, float ay, float bx, float by,
                   float aw, float bw,
                   uint32_t fg_color, uint32_t bg_color = 0x00FFFFFF)

Draws an anti-aliased line that tapers from width aw at the start (ax, ay) to width bw at the end (bx, by), creating a wedge or arrow shape.

float

X start coordinate.

float

Y start coordinate.

float

X end coordinate.

float

Y end coordinate.

float

Half-width at the start point.

float

Half-width at the end point.

fg_color

uint32_t

Line colour.

bg_color

uint32_t

Background colour. Default 0x00FFFFFF reads from display.

// Arrow: wide at start (8px), narrow at end (1px)
tft.drawWedgeLine(20.0f, 120.0f, 180.0f, 120.0f, 8.0f, 1.0f, TFT_MAGENTA, TFT_BLACK);

drawBitmap() — Monochrome Bitmap

// With foreground colour only (background transparent)
void drawBitmap(int16_t x, int16_t y, const uint8_t *bitmap,
                int16_t w, int16_t h, uint16_t fgcolor)

// With foreground and background colours
void drawBitmap(int16_t x, int16_t y, const uint8_t *bitmap,
                int16_t w, int16_t h, uint16_t fgcolor, uint16_t bgcolor)

Draws a 1-bit-per-pixel monochrome bitmap stored in a uint8_t array. Set bits are drawn with fgcolor; clear bits are transparent (overload 1) or drawn with bgcolor (overload 2).

int16_t

X coordinate of the top-left corner.

int16_t

Y coordinate of the top-left corner.

bitmap

const uint8_t *

Pointer to the bitmap data array (MSB first, row-major).

int16_t

Bitmap width in pixels.

int16_t

Bitmap height in pixels.

fgcolor

uint16_t

Colour for set pixels (bit = 1).

bgcolor

uint16_t

Colour for clear pixels (bit = 0). Only in overload 2.

static const uint8_t icon[] PROGMEM = { 0xFF, 0x81, 0x81, 0xFF };
tft.drawBitmap(10, 10, icon, 8, 4, TFT_WHITE, TFT_BLACK);

drawXBitmap() — XBM Format Bitmap

// Transparent background
void drawXBitmap(int16_t x, int16_t y, const uint8_t *bitmap,
                 int16_t w, int16_t h, uint16_t fgcolor)

// Explicit background
void drawXBitmap(int16_t x, int16_t y, const uint8_t *bitmap,
                 int16_t w, int16_t h, uint16_t fgcolor, uint16_t bgcolor)

Draws a bitmap stored in X BitMap (XBM) format. XBM data is LSB-first (the opposite byte order from drawBitmap()), matching the output of the GIMP XBM export and the standard X11 XBM format.

int16_t

X coordinate of the top-left corner.

int16_t

Y coordinate of the top-left corner.

bitmap

const uint8_t *

Pointer to XBM format bitmap data (LSB first).

int16_t

Bitmap width in pixels.

int16_t

Bitmap height in pixels.

fgcolor

uint16_t

Colour for set bits.

bgcolor

uint16_t

Colour for clear bits. Only in overload 2.

// XBM exported from GIMP
static const uint8_t logo_bits[] PROGMEM = { ... };
tft.drawXBitmap(0, 0, logo_bits, 64, 64, TFT_WHITE, TFT_BLACK);

TFT_eSPI Class

TFT_eSPI_Button Class

Constants & Types

TFT_eSPI Shape and Line Outline Drawing API Reference

drawPixel() — Draw a Single Pixel

drawLine() — Arbitrary Line

drawFastHLine() / drawFastVLine() — Optimized Axis-Aligned Lines

drawRect() — Rectangle Outline

drawRoundRect() — Rounded Rectangle Outline

drawSmoothRoundRect() — Anti-Aliased Rounded Rectangle

drawCircle() — Circle Outline

drawSmoothCircle() — Anti-Aliased Circle Outline

drawCircleHelper() — Quadrant Arc Helper

drawEllipse() — Ellipse Outline

drawTriangle() — Triangle Outline

drawArc() — Arc (Configurable Anti-Aliasing)

drawSmoothArc() — Arc with Anti-Aliased Ends

drawSpot() — Anti-Aliased Filled Circle (Sub-Pixel)

drawWideLine() — Anti-Aliased Wide Line (Uniform Width)

drawWedgeLine() — Anti-Aliased Tapered Line

drawBitmap() — Monochrome Bitmap

drawXBitmap() — XBM Format Bitmap

Build docs developers (and LLMs) love

TFT_eSPI Class

TFT_eSPI_Button Class

Constants & Types

Documentation Index

​drawPixel() — Draw a Single Pixel

​drawLine() — Arbitrary Line

​drawFastHLine() / drawFastVLine() — Optimized Axis-Aligned Lines

​drawRect() — Rectangle Outline

​drawRoundRect() — Rounded Rectangle Outline

​drawSmoothRoundRect() — Anti-Aliased Rounded Rectangle

​drawCircle() — Circle Outline

​drawSmoothCircle() — Anti-Aliased Circle Outline

​drawCircleHelper() — Quadrant Arc Helper

​drawEllipse() — Ellipse Outline

​drawTriangle() — Triangle Outline

​drawArc() — Arc (Configurable Anti-Aliasing)

​drawSmoothArc() — Arc with Anti-Aliased Ends

​drawSpot() — Anti-Aliased Filled Circle (Sub-Pixel)

​drawWideLine() — Anti-Aliased Wide Line (Uniform Width)

​drawWedgeLine() — Anti-Aliased Tapered Line

​drawBitmap() — Monochrome Bitmap

​drawXBitmap() — XBM Format Bitmap

Build docs developers (and LLMs) love

drawPixel() — Draw a Single Pixel

drawLine() — Arbitrary Line

drawFastHLine() / drawFastVLine() — Optimized Axis-Aligned Lines

drawRect() — Rectangle Outline

drawRoundRect() — Rounded Rectangle Outline

drawSmoothRoundRect() — Anti-Aliased Rounded Rectangle

drawCircle() — Circle Outline

drawSmoothCircle() — Anti-Aliased Circle Outline

drawCircleHelper() — Quadrant Arc Helper

drawEllipse() — Ellipse Outline

drawTriangle() — Triangle Outline

drawArc() — Arc (Configurable Anti-Aliasing)

drawSmoothArc() — Arc with Anti-Aliased Ends

drawSpot() — Anti-Aliased Filled Circle (Sub-Pixel)

drawWideLine() — Anti-Aliased Wide Line (Uniform Width)

drawWedgeLine() — Anti-Aliased Tapered Line

drawBitmap() — Monochrome Bitmap

drawXBitmap() — XBM Format Bitmap