Drawing Shapes and Primitives with TFT_eSPI Library

TFT_eSPI provides a rich set of primitive drawing functions that cover everything from a single pixel to filled gradient rectangles. All coordinates use a top-left origin — the X-axis increases to the right and the Y-axis increases downward. Outline functions draw the border of a shape, while their fill counterparts flood the interior with a solid color. Choosing the right primitive keeps your rendering fast and your code readable.

Coordinate System

The display origin (0, 0) is the top-left corner. Coordinates and dimensions are always expressed in pixels. Every drawing call clips automatically to the active viewport, so out-of-bounds coordinates are safe.

All color values are 16-bit RGB565 unless otherwise noted. TFT_eSPI ships with named constants such as TFT_RED, TFT_GREEN, TFT_BLUE, TFT_WHITE, TFT_BLACK, and many more.

Pixels

`drawPixel`

Push a single pixel to the display, with optional alpha-blending against a background color.

void     drawPixel(int32_t x, int32_t y, uint32_t color);
uint16_t drawPixel(int32_t x, int32_t y, uint32_t color, uint8_t alpha, uint32_t bg_color = 0x00FFFFFF);

int32_t

required

X coordinate of the pixel.

int32_t

required

Y coordinate of the pixel.

color

uint32_t

required

Pixel color (RGB565).

alpha

uint8_t

Alpha blend value 0 (transparent) to 255 (opaque). Only used in the blending overload.

bg_color

uint32_t

Background color to blend against. Defaults to 0x00FFFFFF, which instructs the library to read the actual pixel from the display.

The blending overload returns the resulting uint16_t pixel color after blending is applied.

tft.drawPixel(10, 10, TFT_RED);                       // Solid red pixel
tft.drawPixel(20, 20, TFT_BLUE, 128, TFT_BLACK);      // 50% blue over black

Lines

`drawLine`

Draw a line between two arbitrary points using Bresenham’s algorithm.

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

int32_t

required

Start X coordinate.

int32_t

required

Start Y coordinate.

int32_t

required

End X coordinate.

int32_t

required

End Y coordinate.

color

uint32_t

required

Line color (RGB565).

tft.drawLine(10, 20, 80, 150, TFT_GREEN);

`drawFastHLine` and `drawFastVLine`

Optimized routines for axis-aligned lines. These are considerably faster than drawLine for horizontal and vertical segments.

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);

int32_t

required

Starting X coordinate.

int32_t

required

Starting Y coordinate.

int32_t

required

drawFastHLine — width (number of pixels to the right).

int32_t

required

drawFastVLine — height (number of pixels downward).

color

uint32_t

required

Line color.

tft.drawFastHLine(10, 20,  100, TFT_RED);    // Horizontal red line, 100 px wide
tft.drawFastVLine(50, 10,  100, TFT_GREEN);  // Vertical green line, 100 px tall

Use drawFastHLine and drawFastVLine whenever you need horizontal or vertical lines — they skip the Bresenham logic entirely and issue a single block transfer to the display.

Rectangles

`drawRect` and `drawRoundRect`

Draw a rectangle outline or a rounded-corner rectangle outline.

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

int32_t

required

X coordinate of the top-left corner.

int32_t

required

Y coordinate of the top-left corner.

int32_t

required

Width in pixels.

int32_t

required

Height in pixels.

radius

int32_t

Corner radius in pixels (drawRoundRect only).

color

uint32_t

required

Border color.

tft.drawRect(10, 10, 50, 30, TFT_RED);           // Plain rectangle
tft.drawRoundRect(20, 20, 60, 40, 10, TFT_BLUE); // Rounded corners, radius=10

`fillRect` and `fillRoundRect`

Filled counterparts of the outline functions above.

void fillRect(int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);
void fillRoundRect(int32_t x, int32_t y, int32_t w, int32_t h, int32_t radius, uint32_t color);

Parameters are identical to their draw counterparts; color sets the fill color.

tft.fillRect(10, 10, 50, 30, TFT_RED);
tft.fillRoundRect(20, 60, 60, 40, 10, TFT_CYAN);

`fillScreen`

Fill the entire display with a single color — the fastest way to clear the screen.

void fillScreen(uint32_t color);

color

uint32_t

required

Fill color.

tft.fillScreen(TFT_BLACK); // Clear to black

Circles

`drawCircle` and `fillCircle`

Draw or fill a circle using the optimized midpoint circle algorithm.

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

int32_t

required

X coordinate of the center.

int32_t

required

Y coordinate of the center.

int32_t

required

Radius in pixels.

color

uint32_t

required

Outline or fill color.

tft.drawCircle(120, 120, 50, TFT_WHITE);  // Circle outline
tft.fillCircle(120, 120, 50, TFT_WHITE);  // Filled circle

Ellipses

`drawEllipse` and `fillEllipse`

Draw or fill an ellipse with independent horizontal and vertical radii.

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

int16_t

required

X coordinate of the center.

int16_t

required

Y coordinate of the center.

int32_t

required

Horizontal radius in pixels.

int32_t

required

Vertical radius in pixels.

color

uint16_t

required

Outline or fill color.

tft.drawEllipse(120, 120, 50, 20, TFT_WHITE); // Wide, shallow ellipse outline
tft.fillEllipse(120, 120, 50, 20, TFT_WHITE); // Filled

Triangles

`drawTriangle` and `fillTriangle`

Draw or fill an arbitrary triangle defined by three vertices.

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

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

x1, y1

int32_t

required

First vertex coordinates.

x2, y2

int32_t

required

Second vertex coordinates.

x3, y3

int32_t

required

Third vertex coordinates.

color

uint32_t

required

Outline or fill color.

tft.drawTriangle(50, 50, 100, 150, 150, 50, TFT_YELLOW);  // Outline only
tft.fillTriangle(50, 50, 100, 150, 150, 50, TFT_YELLOW);  // Filled

Gradient Fills

`fillRectVGradient` and `fillRectHGradient`

Fill a rectangle with a smooth color gradient — either vertical (top-to-bottom) or horizontal (left-to-right).

void fillRectVGradient(int16_t x, int16_t y, int16_t w, int16_t h, uint32_t color1, uint32_t color2);
void fillRectHGradient(int16_t x, int16_t y, int16_t w, int16_t h, uint32_t color1, uint32_t color2);

int16_t

required

X coordinate of the top-left corner.

int16_t

required

Y coordinate of the top-left corner.

int16_t

required

Width in pixels.

int16_t

required

Height in pixels.

color1

uint32_t

required

Start color (top or left).

color2

uint32_t

required

End color (bottom or right).

tft.fillRectVGradient(10, 10, 100, 80, TFT_BLUE,   TFT_BLACK); // Blue → black, top to bottom
tft.fillRectHGradient(10, 100, 100, 80, TFT_RED, TFT_YELLOW);  // Red → yellow, left to right

Practical Example

The following sketch draws a small scene that combines most of the primitives covered above.

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);         // Clear to black

  // Sky gradient
  tft.fillRectVGradient(0, 0, 320, 120, TFT_NAVY, TFT_BLACK);

  // Ground
  tft.fillRect(0, 120, 320, 120, TFT_DARKGREEN);

  // Sun (filled yellow circle with white outline)
  tft.fillCircle(260, 50, 30, TFT_YELLOW);
  tft.drawCircle(260, 50, 30, TFT_WHITE);

  // House body
  tft.fillRect(90, 100, 100, 80, TFT_LIGHTGREY);
  tft.drawRect(90, 100, 100, 80, TFT_WHITE);

  // Roof (triangle)
  tft.fillTriangle(80, 100, 140, 50, 200, 100, TFT_RED);
  tft.drawTriangle(80, 100, 140, 50, 200, 100, TFT_WHITE);

  // Door
  tft.fillRoundRect(125, 145, 30, 35, 4, TFT_BROWN);

  // Window
  tft.fillRect(155, 110, 25, 25, TFT_CYAN);
  tft.drawRect(155, 110, 25, 25, TFT_WHITE);

  // Path lines
  tft.drawFastVLine(140, 180, 60, TFT_YELLOW);
  tft.drawFastHLine(100, 200, 80, TFT_YELLOW);

  // Ellipse pond
  tft.fillEllipse(60, 210, 40, 15, TFT_BLUE);
  tft.drawEllipse(60, 210, 40, 15, TFT_WHITE);
}

void loop() {}

TFT_BROWN and TFT_DARKGREEN may not be defined in all TFT_eSPI builds. Replace them with tft.color565(r, g, b) calls if needed, e.g. tft.color565(139, 69, 19) for brown.

Getting Started

Core Concepts

Drawing & Graphics

Advanced Topics

Hardware

Examples

Drawing Shapes and Primitives with TFT_eSPI Library

Coordinate System

Pixels

`drawPixel`

Lines

`drawLine`

`drawFastHLine` and `drawFastVLine`

Rectangles

`drawRect` and `drawRoundRect`

`fillRect` and `fillRoundRect`

`fillScreen`

Circles

`drawCircle` and `fillCircle`

Ellipses

`drawEllipse` and `fillEllipse`

Triangles

`drawTriangle` and `fillTriangle`

Gradient Fills

`fillRectVGradient` and `fillRectHGradient`

Practical Example

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Drawing & Graphics

Advanced Topics

Hardware

Examples

Documentation Index

​Coordinate System

​Pixels

​drawPixel

​Lines

​drawLine

​drawFastHLine and drawFastVLine

​Rectangles

​drawRect and drawRoundRect

​fillRect and fillRoundRect

​fillScreen

​Circles

​drawCircle and fillCircle

​Ellipses

​drawEllipse and fillEllipse

​Triangles

​drawTriangle and fillTriangle

​Gradient Fills

​fillRectVGradient and fillRectHGradient

​Practical Example

Build docs developers (and LLMs) love

Coordinate System

Pixels

`drawPixel`

Lines

`drawLine`

`drawFastHLine` and `drawFastVLine`

Rectangles

`drawRect` and `drawRoundRect`

`fillRect` and `fillRoundRect`

`fillScreen`

Circles

`drawCircle` and `fillCircle`

Ellipses

`drawEllipse` and `fillEllipse`

Triangles

`drawTriangle` and `fillTriangle`

Gradient Fills

`fillRectVGradient` and `fillRectHGradient`

Practical Example