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 separates the concept of the text cursor (used by print() / println() and respected by drawChar()) from the drawing origin (a coordinate offset applied to all drawing commands). The display can be rotated to any of four orientations without reinitializing the hardware. Low-level pixel-streaming helpers (pushColor(), pushColors(), pushBlock(), pushPixels()) allow efficient bulk writes when the address window has been set manually. SPI transactions can be batched with startWrite() / endWrite() for a significant throughput improvement when performing many consecutive drawing operations.

​
setCursor() — Position the Text Cursor

void setCursor(int16_t x, int16_t y)
void setCursor(int16_t x, int16_t y, uint8_t font)
Sets the text cursor to the given screen coordinates. The second overload also selects the active font. The cursor position is used by print(), println(), and drawChar() when no explicit position is supplied.
​
x
int16_t
X coordinate for the cursor (top-left of the next character).
​
y
int16_t
Y coordinate for the cursor.
​
font
uint8_t
Font number to activate (1–8). Only available in the three-argument overload.
tft.setCursor(10, 20);
tft.setTextColor(TFT_WHITE, TFT_BLACK);
tft.println("Hello!");

// With font selection
tft.setCursor(10, 60, 4);
tft.print("Font 4");

​
getCursorX() / getCursorY() — Read Cursor Position

int16_t getCursorX(void)
int16_t getCursorY(void)
Return the current text cursor coordinates. The cursor advances automatically after each character rendered by print() or println(), so these getters are useful for continuing text after a drawString() call or for measuring how far text has advanced. Returns: int16_t — current cursor X or Y position in pixels. 
tft.setCursor(10, 30);
tft.print("Partial ");
int16_t cx = tft.getCursorX(); // position right after "Partial "
tft.setTextColor(TFT_YELLOW);
tft.print("coloured");

​
setRotation() — Set Display Orientation

void setRotation(uint8_t r)
Rotates the display coordinate system without reinitializing the hardware. After rotation, (0, 0) is always the top-left corner of the new orientation, and width() / height() update accordingly.
​
r
uint8_t
Rotation value (0–3):
  • 0 — Portrait, 0° (default)
  • 1 — Landscape, 90° clockwise
  • 2 — Portrait, 180°
  • 3 — Landscape, 270° clockwise
tft.setRotation(1); // landscape mode
tft.fillScreen(TFT_BLACK);

​
getRotation() — Read Current Orientation

uint8_t getRotation(void)
Returns the current rotation setting. Returns: uint8_t — value 0–3 matching the last call to setRotation(). 
if (tft.getRotation() != 1) {
  tft.setRotation(1);
}

​
setOrigin() — Set Drawing Coordinate Offset

void setOrigin(int32_t x, int32_t y)
Sets a global coordinate offset applied to all subsequent drawing operations. Positive values shift the origin right and down. This is distinct from the viewport — the viewport clips drawing, while the origin only translates coordinates.
​
x
int32_t
Horizontal offset in pixels. Positive shifts drawing to the right.
​
y
int32_t
Vertical offset in pixels. Positive shifts drawing downward.
tft.setOrigin(20, 40); // all coordinates are offset by (20, 40)
tft.drawRect(0, 0, 50, 30, TFT_WHITE); // actually at screen (20, 40)
tft.setOrigin(0, 0);   // reset origin

​
getOriginX() / getOriginY() — Read Drawing Origin

int32_t getOriginX(void)
int32_t getOriginY(void)
Return the current drawing origin offset. Returns: int32_t — current X or Y origin offset in pixels.

​
invertDisplay() — Invert Panel Colours

void invertDisplay(bool i)
Sends the hardware colour-inversion command to the display driver. Operates at the panel level with no CPU overhead per pixel.
​
i
bool
true to invert colours; false to restore normal colours.
tft.invertDisplay(true);
delay(500);
tft.invertDisplay(false);

​
pushColor() — Push a Single Colour

void pushColor(uint16_t color)
void pushColor(uint16_t color, uint32_t len)
Writes one or len copies of color to the current address window. The address window must be set in advance with setAddrWindow() or setWindow().
​
color
uint16_t
RGB565 colour to push.
​
len
uint32_t
Number of pixels to write. Only in the two-argument overload.
tft.setAddrWindow(10, 10, 50, 50);
tft.pushColor(TFT_RED, 50 * 50); // fill 50×50 window with red

​
pushColors() — Push an Array of Colours

void pushColors(uint16_t *data, uint32_t len, bool swap = true)
void pushColors(uint8_t  *data, uint32_t len)
Streams an array of pixel values into the current address window. The first overload accepts 16-bit RGB565 data and can optionally byte-swap each word (default true). The second overload accepts raw 8-bit data.
​
data
uint16_t * or uint8_t *
Pointer to pixel colour data.
​
len
uint32_t
Number of pixels (16-bit overload) or bytes (8-bit overload) to push.
​
swap
bool
If true (default), byte-swaps each 16-bit value before sending. Only applies to the 16-bit overload.
uint16_t pixels[100];
// fill pixels[] ...
tft.setAddrWindow(0, 0, 10, 10);
tft.pushColors(pixels, 100, true);

​
pushBlock() — Push a Solid Colour Block

void pushBlock(uint16_t color, uint32_t len)
Writes len copies of color to the SPI bus as efficiently as possible. Unlike pushColor(), this bypasses the CS assertion loop on platforms that support block transfers.
​
color
uint16_t
RGB565 fill colour.
​
len
uint32_t
Number of pixels to write.

​
pushPixels() — Push Raw Pixel Data

void pushPixels(const void *data_in, uint32_t len)
Sends raw pixel data directly to the SPI interface. The data must already be in the correct byte order for the display. Used internally by sprite and image push routines.
​
data_in
const void *
Pointer to raw pixel data.
​
len
uint32_t
Number of pixels to send.

​
startWrite() / endWrite() / writeColor() — SPI Transaction Batching

void startWrite(void)
void endWrite(void)
void writeColor(uint16_t color, uint32_t len)
startWrite() asserts the chip-select line and begins an SPI transaction, holding it open across multiple draw calls. endWrite() releases the chip-select. Batching multiple operations between startWrite() / endWrite() eliminates the CS toggle overhead between calls and can significantly increase throughput. writeColor() writes len pixels of color inside an already-open transaction without managing CS — it must be called between startWrite() and endWrite().
​
color
uint16_t
RGB565 colour for writeColor().
​
len
uint32_t
Number of pixels for writeColor().
tft.startWrite();
  tft.setAddrWindow(0, 0, 240, 320);
  for (int i = 0; i < 240 * 320; i++) {
    tft.writeColor(TFT_NAVY, 1);
  }
tft.endWrite();
Wrapping many drawing calls in a single startWrite() / endWrite() pair reduces SPI overhead substantially. For DMA transfers use pushImageDMA() inside the transaction instead.

​
getSPIinstance() — Access the SPI Class Handle

static SPIClass& getSPIinstance(void)
Returns a reference to the SPIClass instance managed by TFT_eSPI. Useful when another SPI device shares the bus and you need to coordinate bus access or change settings.
getSPIinstance() is not available when TFT_PARALLEL_8_BIT or RP2040_PIO_INTERFACE is defined, as those interfaces do not use the Arduino SPI class.
Returns: SPIClass& — reference to the SPI instance. 
SPIClass& spi = TFT_eSPI::getSPIinstance();
spi.setFrequency(8000000); // change SPI clock

Build docs developers (and LLMs) love

Get started for freeTalk to us