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 every pixel color as a 16-bit uint16_t value in the RGB565 format. Understanding this encoding helps you work confidently with the predefined color constants, convert between color spaces, and handle transparency in sprites.

​
The RGB565 Color Format

RGB565 packs a full color into 16 bits by allocating:
  • 5 bits for Red (values 0 – 31, mapped to 0 – 255)
  • 6 bits for Green (values 0 – 63, mapped to 0 – 255 — one extra bit because the human eye is most sensitive to green)
  • 5 bits for Blue (values 0 – 31, mapped to 0 – 255)
The bit layout from most-significant to least-significant is: 
Bit:  15 14 13 12 11 | 10  9  8  7  6  5 |  4  3  2  1  0
      R4 R3 R2 R1 R0   G5 G4 G3 G2 G1 G0   B4 B3 B2 B1 B0
This gives 65,536 distinct colors — far fewer than 24-bit RGB but enough for rich UIs on microcontroller displays, and small enough to fit two pixels in a single 32-bit register.

​
Predefined Color Constants

TFT_eSPI ships with 25 ready-to-use color constants. All of them are int32_t values expressed as 16-bit RGB565 words.
ConstantHex ValueRedGreenBlueNotes
TFT_BLACK0x0000000
TFT_NAVY0x000F00128
TFT_DARKGREEN0x03E001280
TFT_DARKCYAN0x03EF0128128
TFT_MAROON0x780012800
TFT_PURPLE0x780F1280128
TFT_OLIVE0x7BE01281280
TFT_LIGHTGREY0xD69A211211211
TFT_DARKGREY0x7BEF128128128
TFT_BLUE0x001F00255
TFT_GREEN0x07E002550
TFT_CYAN0x07FF0255255
TFT_RED0xF80025500
TFT_MAGENTA0xF81F2550255
TFT_YELLOW0xFFE02552550
TFT_WHITE0xFFFF255255255
TFT_ORANGE0xFDA02551800
TFT_GREENYELLOW0xB7E01802550
TFT_PINK0xFE19255192203Lighter pink (was 0xFC9F)
TFT_BROWN0x9A60150750
TFT_GOLD0xFEA02552150
TFT_SILVER0xC618192192192
TFT_SKYBLUE0x867D135206235
TFT_VIOLET0x915C18046226
TFT_TRANSPARENT0x0120———Special value — see section below

​
TFT_TRANSPARENT Special Value

TFT_TRANSPARENT (0x0120) is a reserved sentinel color used with sprites. It is not a true color in the artistic sense — it is a carefully chosen 16-bit value that:
  1. Encodes to the same 8-bit representation when stored in an 8-bit sprite.
  2. Decodes back to the identical 16-bit value, making round-trips lossless.
  3. Visually appears as a very dark green, which is unlikely to clash with real UI content.
When you push a sprite to the display and mark TFT_TRANSPARENT as the transparent color key, any pixel with this value is skipped rather than drawn, producing true sprite transparency without a dedicated alpha channel.
Use TFT_TRANSPARENT only as a color key for sprite transparency. Avoid it as an intentional dark-green fill color, or transparency detection will misfire.

​
Default 4-Bit Palette for Sprites

TFT_eSprite supports 4-bit (16-color) sprites using a fixed palette stored in flash as default_4bit_palette[]. The 16 entries follow the classic resistor color-code sequence for indices 0 – 9:
IndexColor ConstantNotes
0TFT_BLACKResistor color code start ↑
1TFT_BROWN
2TFT_RED
3TFT_ORANGE
4TFT_YELLOW
5TFT_GREEN
6TFT_BLUE
7TFT_PURPLE
8TFT_DARKGREYResistor color code end ↓
9TFT_WHITE
10TFT_CYANBlue + green mix
11TFT_MAGENTABlue + red mix
12TFT_MAROONDarker red
13TFT_DARKGREENDarker green
14TFT_NAVYDarker blue
15TFT_PINK

​
Color Conversion Functions

TFT_eSPI provides several helper methods for converting between color spaces. All are members of the TFT_eSPI class:

color565()

Convert 8-bit R, G, B components to a 16-bit RGB565 value.
uint16_t color565(uint8_t red,
                  uint8_t green,
                  uint8_t blue);

color8to16()

Expand a packed 8-bit RGB332 color to 16-bit RGB565.
uint16_t color8to16(uint8_t color332);

color16to24()

Convert a 16-bit RGB565 value to a 24-bit RGB888 uint32_t.
uint32_t color16to24(uint16_t color565);

alphaBlend()

Alpha-blend a foreground color over a background color with an 8-bit alpha (0 = fully transparent, 255 = fully opaque).
uint16_t alphaBlend(uint8_t alpha,
                    uint16_t fgc,
                    uint16_t bgc);

​
Practical Color Conversion Example

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

void setup() {
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);

  // Build a custom coral color from 8-bit RGB components
  uint16_t coral = tft.color565(255, 127, 80);
  tft.fillRect(10, 10, 100, 60, coral);

  // Blend TFT_RED 50% over TFT_BLUE
  uint16_t blended = tft.alphaBlend(128, TFT_RED, TFT_BLUE);
  tft.fillRect(120, 10, 100, 60, blended);

  // Convert a 16-bit color to 24-bit for use in other APIs
  uint32_t rgb24 = tft.color16to24(TFT_CYAN);
  // rgb24 = 0x0000FFFF (R=0, G=255, B=255)
}

void loop() {}
When sourcing colors from a design tool that provides hex RGB values like #FF7F50, convert them with tft.color565(0xFF, 0x7F, 0x50) to get the correct 16-bit representation. Direct assignment of 24-bit hex literals will produce the wrong color.

Build docs developers (and LLMs) love

Get started for freeTalk to us