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.

Working with TFT_eSPI begins with creating a class instance and running a handful of setup calls before any pixels can be drawn. This page walks through every step of that process — from the constructor and initialization methods, through rotation modes, to the coordinate system that governs where everything appears on screen.

​
Instantiating TFT_eSPI

The TFT_eSPI class is the central object you interact with throughout your sketch. Declare one global instance before setup() so it is accessible everywhere: 
// Use the dimensions defined in User_Setup.h (most common)
TFT_eSPI tft = TFT_eSPI();

// Or explicitly override width and height at construction time
TFT_eSPI tft = TFT_eSPI(320, 240);
Constructor signature: 
TFT_eSPI(int16_t _W = TFT_WIDTH, int16_t _H = TFT_HEIGHT)
Both parameters default to the values set in your User_Setup.h configuration file, so the no-argument form is almost always correct. Providing explicit dimensions is useful when you want to use a smaller logical canvas than the physical panel.

​
Initializing the Display

Before any drawing function will work you must call init() (or its alias begin()). Both methods perform the same hardware initialization sequence — begin() exists purely for backwards compatibility with older sketches. 
void TFT_eSPI::init(uint8_t tc = TAB_COLOUR);
void TFT_eSPI::begin(uint8_t tc = TAB_COLOUR);
The optional tc (tab colour) parameter applies only to ST7735 displays and selects the display variant. For every other controller you can omit it entirely and rely on the TAB_COLOUR default.
init() and begin() are fully interchangeable. New sketches should prefer init() for clarity, but both compile to identical code.

​
Configuring Screen Rotation

After initialization you will typically call setRotation() to orient the display correctly for your enclosure or use-case: 
void TFT_eSPI::setRotation(uint8_t m);
The m parameter accepts values 0 – 3, each rotating the coordinate system by a multiple of 90 degrees:
ValueOrientationWidth → Height
0Portrait (default)native W × H
1Landscape (90° CW)native H × W
2Portrait flipped (180°)native W × H
3Landscape flipped (270°)native H × W
Values 4 – 7 are also accepted and mirror their 0 – 3 counterparts for use with BMP drawing routines.
Always call setRotation() before your first drawing command. Changing rotation mid-sketch does not redraw existing pixels — you will need to clear the screen with fillScreen() after rotating.

​
Complete Setup Example

The following is a typical setup() function drawn directly from library examples: 
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.init();                              // Initialize the display hardware
  tft.setRotation(1);                      // Landscape orientation

  tft.fillScreen(TFT_BLACK);              // Clear screen to black
  tft.setCursor(0, 0);                    // Move text cursor to top-left
  tft.setTextColor(TFT_WHITE);            // White text, transparent background
  tft.setTextSize(2);                     // 2× size multiplier
  tft.setTextFont(2);                     // Built-in 16 px font
  tft.println("Hello World!");
}

void loop() {
  // Drawing and updates go here
}
1

Declare the instance

Create a global TFT_eSPI tft before setup() so the object is accessible from every function.
2

Call init() or begin()

Run tft.init() at the very start of setup() to configure SPI, reset the panel, and apply driver settings.
3

Set rotation

Call tft.setRotation(n) immediately after init to establish the coordinate system before any drawing.
4

Clear the screen

Use tft.fillScreen(TFT_BLACK) to start with a known blank canvas.
5

Draw content

Position text with setCursor(), set colors and fonts, then call print() / drawString() or any drawing primitive.

​
Coordinate System Overview

TFT_eSPI uses a pixel-based Cartesian coordinate system with the origin (0, 0) fixed at the top-left corner of the display after rotation is applied:
  • The X axis increases from left to right.
  • The Y axis increases from top to bottom.
  • Every coordinate is expressed in whole pixels.
This means the bottom-right corner of a 320 × 240 display in landscape mode sits at (319, 239).

​
Querying Current Dimensions

After setRotation() the logical width and height of the screen change. Use the two dimension accessors to write rotation-aware code: 
int16_t TFT_eSPI::width(void);   // Current width in pixels
int16_t TFT_eSPI::height(void);  // Current height in pixels
Both methods return the rotated dimensions, so width() and height() always reflect what is currently visible: 
// Works correctly in any rotation
int centerX = tft.width()  / 2;
int centerY = tft.height() / 2;

tft.setCursor(centerX, centerY);
tft.print("Centered!");
width() and height() are virtual methods inherited through the display driver chain, so they also work correctly on TFT_eSprite objects that share the same coordinate API.

Build docs developers (and LLMs) love

Get started for freeTalk to us