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.

The TFT_eSPI class is a hardware-accelerated TFT graphics library targeting ESP8266, ESP32, RP2040, and STM32 boards. It provides a comprehensive set of drawing primitives, text rendering, color utilities, viewport clipping, and DMA-assisted pixel pushing — all in a single unified class. The current release is identified by the constant TFT_ESPI_VERSION "2.5.43", and the library’s feature flag TFT_ESPI_FEATURES 1 signals that viewport/clipping capability is compiled in. TFT_eSPI inherits from the Arduino Print class, which means the familiar print() and println() methods are available for streaming text to the display at the current cursor position, in addition to the purpose-built draw string methods. TFT_eSprite is declared as a friend class and shares internal state for off-screen sprite rendering.

​
Library Constants

#define TFT_ESPI_VERSION  "2.5.43"   // Library version string
#define TFT_ESPI_FEATURES 1          // Bit 0 set: viewport capability enabled
#define TAB_COLOUR        0          // Default ST7735 tab colour
#define CP437_SWITCH      1          // setAttribute id: enable/disable CP437 font correction
#define UTF8_SWITCH       2          // setAttribute id: enable/disable UTF-8 decoding
#define PSRAM_ENABLE      3          // setAttribute id: enable/disable PSRAM usage

​
Key Public Member Variables

VariableTypeDescription
textcoloruint32_tCurrent text foreground colour
textbgcoloruint32_tCurrent text background colour
bitmap_fguint32_tBitmap foreground colour (bit = 1)
bitmap_bguint32_tBitmap background colour (bit = 0)
textfontuint8_tCurrently selected font number
textsizeuint8_tCurrent font size multiplier
textdatumuint8_tText reference datum (alignment)
rotationuint8_tDisplay rotation (0–3)
DMA_Enabledbooltrue when DMA transfers are active

​
API Method Groups

Constructor & Init

Construct the TFT object, call begin() or init(), set rotation, retrieve setup diagnostics, and verify the setup ID.

Drawing Shapes

Draw outlines of pixels, lines, rectangles, circles, ellipses, triangles, arcs, bitmaps, and anti-aliased smooth shapes.

Filling Shapes

Fill the screen or any closed shape — rectangles, rounded rectangles, circles, ellipses, triangles — including gradient fills.

Text Methods

Render strings, characters, numbers, and floats; configure fonts, text size, colour, datum, padding, and wrapping.

Color & Pixel

Read pixels, convert between RGB colour spaces, alpha-blend colours, push images and pixel buffers to the display.

Cursor & Rotation

Manage the text cursor position, display rotation, drawing origin, colour push helpers, and SPI transaction control.

Viewport & Window

Define viewport clipping regions, draw frame borders, set low-level address windows, and clip draw commands.

​
setup_t Structure

The setup_t structure can be populated by calling getSetup() and is useful for diagnostic sketches to inspect the compiled library configuration at runtime. 
typedef struct {
  String   version;       // TFT_ESPI_VERSION
  String   setup_info;    // Setup reference name
  uint32_t setup_id;      // ID from user setup
  int32_t  esp;           // Processor code
  uint8_t  trans;         // SPI transaction support
  uint8_t  serial;        // Serial (SPI) or parallel
  uint8_t  port;          // SPI port (not on GENERIC_PROCESSOR)
  uint8_t  overlap;       // ESP8266 overlap mode
  uint8_t  interface;     // Interface type

  uint16_t tft_driver;    // Driver code in hex
  uint16_t tft_width;     // Rotation-0 width
  uint16_t tft_height;    // Rotation-0 height

  // Display offsets per rotation (r0..r3)
  uint8_t  r0_x_offset, r0_y_offset;
  uint8_t  r1_x_offset, r1_y_offset;
  uint8_t  r2_x_offset, r2_y_offset;
  uint8_t  r3_x_offset, r3_y_offset;

  // SPI pins
  int8_t   pin_tft_mosi, pin_tft_miso;
  int8_t   pin_tft_clk,  pin_tft_cs;

  // Control pins
  int8_t   pin_tft_dc, pin_tft_rd;
  int8_t   pin_tft_wr, pin_tft_rst;

  // Parallel port pins (d0–d7)
  int8_t   pin_tft_d0, pin_tft_d1;
  int8_t   pin_tft_d2, pin_tft_d3;
  int8_t   pin_tft_d4, pin_tft_d5;
  int8_t   pin_tft_d6, pin_tft_d7;

  int8_t   pin_tft_led, pin_tft_led_on;
  int8_t   pin_tch_cs;      // Touch chip-select

  int16_t  tft_spi_freq;    // TFT write SPI frequency
  int16_t  tft_rd_freq;     // TFT read SPI frequency
  int16_t  tch_spi_freq;    // Touch SPI frequency
} setup_t;

​
Predefined Color Constants

TFT_eSPI ships with a palette of ready-to-use RGB565 colour constants: 
TFT_BLACK       // 0x0000
TFT_WHITE       // 0xFFFF
TFT_RED         // 0xF800
TFT_GREEN       // 0x07E0
TFT_BLUE        // 0x001F
TFT_CYAN        // 0x07FF
TFT_MAGENTA     // 0xF81F
TFT_YELLOW      // 0xFFE0
TFT_ORANGE      // 0xFDA0
TFT_NAVY        // 0x000F
TFT_DARKGREEN   // 0x03E0
TFT_PURPLE      // 0x780F
TFT_TRANSPARENT // 0x0120  (encodes to 8-bit and back losslessly)
// ...and more

​
Text Datum Constants

Use these with setTextDatum() to control text alignment relative to the x, y coordinate passed to draw functions:
ConstantValueDescription
TL_DATUM0Top left (default)
TC_DATUM1Top centre
TR_DATUM2Top right
ML_DATUM3Middle left
MC_DATUM4Middle centre
MR_DATUM5Middle right
BL_DATUM6Bottom left
BC_DATUM7Bottom centre
BR_DATUM8Bottom right
L_BASELINE9Left character baseline
C_BASELINE10Centre character baseline
R_BASELINE11Right character baseline

Build docs developers (and LLMs) love

Get started for freeTalk to us