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 represents colours internally as 16-bit RGB565 values (5 red bits, 6 green bits, 5 blue bits), but provides a suite of conversion helpers for moving between RGB565, 8-bit RGB332, 24-bit RGB888, and alpha-blended composites. The library also exposes methods for reading individual pixels back from the display, pushing raw pixel buffers, and managing image stride and byte-swap settings. DMA-capable pushImage variants are available for high-throughput transfers on ESP32 and RP2040 targets.

​
readPixel() — Read a Pixel from the Display

uint16_t readPixel(int32_t x, int32_t y)
Reads the RGB565 colour value of a single pixel from the display hardware. Requires the MISO line to be connected and configured.
​
x
int32_t
X coordinate of the pixel to read.
​
y
int32_t
Y coordinate of the pixel to read.
Returns: uint16_t — the pixel colour in RGB565 format. 
uint16_t px = tft.readPixel(60, 40);
Serial.print("Pixel colour: 0x");
Serial.println(px, HEX);

​
width() / height() — Display Dimensions

int16_t width(void)
int16_t height(void)
Return the pixel dimensions of the display for the current rotation. After a call to setRotation(1) (landscape), width() returns the longer dimension and height() the shorter, swapped relative to rotation 0. Returns: int16_t — current display width or height in pixels. 
int xCenter = tft.width()  / 2;
int yCenter = tft.height() / 2;
tft.drawCircle(xCenter, yCenter, 50, TFT_WHITE);

​
color565() — Pack RGB Components to RGB565

uint16_t color565(uint8_t red, uint8_t green, uint8_t blue)
Converts 8-bit-per-channel RGB values to a 16-bit RGB565 colour suitable for use in any TFT_eSPI drawing call.
​
red
uint8_t
Red channel intensity (0–255).
​
green
uint8_t
Green channel intensity (0–255).
​
blue
uint8_t
Blue channel intensity (0–255).
Returns: uint16_t — packed RGB565 colour value. 
uint16_t orange = tft.color565(255, 165, 0);
tft.fillRect(0, 0, 100, 100, orange);

​
color8to16() — RGB332 to RGB565

uint16_t color8to16(uint8_t color332)
Expands an 8-bit RGB332 colour (3 red bits, 3 green bits, 2 blue bits) to 16-bit RGB565.
​
color332
uint8_t
8-bit RGB332 packed colour value.
Returns: uint16_t — equivalent RGB565 colour.

​
color16to8() — RGB565 to RGB332

uint8_t color16to8(uint16_t color565)
Reduces a 16-bit RGB565 colour to 8-bit RGB332 (lossy).
​
color565
uint16_t
16-bit RGB565 colour to convert.
Returns: uint8_t — 8-bit RGB332 approximation.

​
color16to24() — RGB565 to RGB888

uint32_t color16to24(uint16_t color565)
Expands a 16-bit RGB565 colour to a 24-bit RGB888 value stored in the lower 3 bytes of a uint32_t.
​
color565
uint16_t
16-bit RGB565 colour.
Returns: uint32_t — 24-bit RGB888 value (bits 23–0 contain the colour; bits 31–24 are 0). 
uint32_t rgb888 = tft.color16to24(TFT_CYAN); // 0x0000FFFF

​
color24to16() — RGB888 to RGB565

uint32_t color24to16(uint32_t color888)
Converts a 24-bit RGB888 colour to 16-bit RGB565 (lossy).
​
color888
uint32_t
24-bit RGB888 colour value (upper byte ignored).
Returns: uint32_t — the RGB565 value in the lower 16 bits. 
uint32_t c565 = tft.color24to16(0xFF8C00); // dark orange in RGB565

​
alphaBlend() — Alpha Composite Two RGB565 Colours

// Without dithering
uint16_t alphaBlend(uint8_t alpha, uint16_t fgc, uint16_t bgc)

// With optional dithering
uint16_t alphaBlend(uint8_t alpha, uint16_t fgc, uint16_t bgc, uint8_t dither)
Blends foreground colour fgc over background colour bgc using an alpha value in the range 0–255. At alpha = 0 the result is fully bgc; at alpha = 255 the result is fully fgc. The dithered overload adds a small noise value to reduce colour banding.
​
alpha
uint8_t
Blend factor (0 = fully background, 255 = fully foreground).
​
fgc
uint16_t
Foreground RGB565 colour.
​
bgc
uint16_t
Background RGB565 colour.
​
dither
uint8_t
Dither amplitude (overload 2 only). Higher values reduce banding.
Returns: uint16_t — blended RGB565 colour. 
uint16_t blended = tft.alphaBlend(128, TFT_RED, TFT_BLACK); // 50% red
tft.drawPixel(50, 50, blended);

​
alphaBlend24() — Alpha Composite Two RGB888 Colours

uint32_t alphaBlend24(uint8_t alpha, uint32_t fgc, uint32_t bgc, uint8_t dither = 0)
Like alphaBlend() but operates on 24-bit RGB888 colours and returns a 24-bit result.
​
alpha
uint8_t
Blend factor (0–255).
​
fgc
uint32_t
Foreground 24-bit colour.
​
bgc
uint32_t
Background 24-bit colour.
​
dither
uint8_t
Dither amplitude. Default 0.
Returns: uint32_t — blended 24-bit colour.

​
setBitmapColor() — Set Bitmap Foreground/Background

void setBitmapColor(uint16_t fgcolor, uint16_t bgcolor)
Sets the foreground and background colours used when rendering 1-bit bitmaps with drawBitmap() and drawXBitmap(). Stored in the public members bitmap_fg and bitmap_bg.
​
fgcolor
uint16_t
Colour for set (1) bits.
​
bgcolor
uint16_t
Colour for clear (0) bits.
tft.setBitmapColor(TFT_WHITE, TFT_BLACK);

​
setSwapBytes() / getSwapBytes() — Byte Order for Image Data

void setSwapBytes(bool swap)
bool getSwapBytes(void)
Controls whether byte pairs in image data passed to pushImage() are swapped before rendering. This corrects the byte order for images stored in little-endian format (e.g. most BMP files on ESP32) versus the big-endian SPI display format.
​
swap
bool
true to swap bytes; false for native order.
getSwapBytes() Returns: bool — current swap-bytes setting. 
tft.setSwapBytes(true);  // images stored in little-endian order

​
readRect() — Read a Pixel Rectangle into a Buffer

void readRect(int32_t x, int32_t y, int32_t w, int32_t h, uint16_t *data)
Reads a rectangular block of RGB565 pixels from the display into a caller-supplied buffer. Requires MISO to be connected.
​
x
int32_t
X coordinate of the top-left corner.
​
y
int32_t
Y coordinate of the top-left corner.
​
w
int32_t
Width of the rectangle in pixels.
​
h
int32_t
Height of the rectangle in pixels.
​
data
uint16_t *
Buffer to receive w * h RGB565 values.
uint16_t buf[100 * 80];
tft.readRect(10, 10, 100, 80, buf);

​
pushRect() — Write a Pixel Rectangle from a Buffer

void pushRect(int32_t x, int32_t y, int32_t w, int32_t h, uint16_t *data)
Pushes a buffer of w * h RGB565 pixels to the display at position (x, y).
​
x
int32_t
X destination coordinate.
​
y
int32_t
Y destination coordinate.
​
w
int32_t
Rectangle width.
​
h
int32_t
Rectangle height.
​
data
uint16_t *
Source buffer of w * h RGB565 values.
tft.pushRect(10, 10, 100, 80, buf);

​
pushImage() — Push Image with Optional Transparency

// 16-bit RGB565 image, no transparency
void pushImage(int32_t x, int32_t y, int32_t w, int32_t h, uint16_t *data)

// 16-bit RGB565 image with transparent colour key
void pushImage(int32_t x, int32_t y, int32_t w, int32_t h,
               uint16_t *data, uint16_t transparent)

// Const pointer variant
void pushImage(int32_t x, int32_t y, int32_t w, int32_t h,
               const uint16_t *data, uint16_t transparent)
void pushImage(int32_t x, int32_t y, int32_t w, int32_t h,
               const uint16_t *data)

// 8-bit palette image
void pushImage(int32_t x, int32_t y, int32_t w, int32_t h,
               uint8_t *data, bool bpp8 = true, uint16_t *cmap = nullptr)

// 8-bit palette image with transparent index
void pushImage(int32_t x, int32_t y, int32_t w, int32_t h,
               uint8_t *data, uint8_t transparent,
               bool bpp8 = true, uint16_t *cmap = nullptr)
Pushes a rectangular image to the display. Multiple overloads support 16-bit RGB565, 8-bit palettized (with optional colour map), and transparent-colour-key variants.
​
x
int32_t
X destination coordinate.
​
y
int32_t
Y destination coordinate.
​
w
int32_t
Image width in pixels.
​
h
int32_t
Image height in pixels.
​
data
uint16_t * or uint8_t *
Pointer to pixel data.
​
transparent
uint16_t or uint8_t
Transparent colour key. Pixels matching this value are not rendered.
​
bpp8
bool
When true, each uint8_t is a palette index; when false, it’s raw RGB332.
​
cmap
uint16_t *
Pointer to a 256-entry RGB565 colour-map array. nullptr uses a default map.
extern const uint16_t myImage[240 * 320];
tft.setSwapBytes(true);
tft.pushImage(0, 0, 240, 320, myImage);

​
pushMaskedImage() — Push Image with Alpha Mask

void pushMaskedImage(int32_t x, int32_t y, int32_t w, int32_t h,
                     uint16_t *img, uint8_t *mask)
Pushes a 16-bit image, applying a 1-bit-per-pixel mask. Masked-out pixels are not written to the display.
​
x
int32_t
X destination coordinate.
​
y
int32_t
Y destination coordinate.
​
w
int32_t
Image width.
​
h
int32_t
Image height.
​
img
uint16_t *
RGB565 pixel data.
​
mask
uint8_t *
1-bit mask data (1 = render pixel, 0 = skip).

​
setPivot() / getPivotX() / getPivotY() — Sprite Pivot Point

void    setPivot(int16_t x, int16_t y)
int16_t getPivotX(void)
int16_t getPivotY(void)
Sets or reads the pivot point used when pushing rotated sprites to the TFT. The pivot is expressed in TFT screen coordinates.
​
x
int16_t
X coordinate of the pivot point.
​
y
int16_t
Y coordinate of the pivot point.
Returns (getPivotX/Y): int16_t — pivot coordinate. 
tft.setPivot(tft.width() / 2, tft.height() / 2); // centre pivot
int16_t px = tft.getPivotX();
int16_t py = tft.getPivotY();

Build docs developers (and LLMs) love

Get started for freeTalk to us