Graphics Library

This tutorial is for the original 2.8" TFT breakout, we have an updated tutorial now at https://learn.adafruit.com/adafruit-2-dot-8-color-tft-touchscreen-breakout-v2 for the most recent version of this product, but are keeping this tutorial for historical reference
The graphics library has a few ready to go functions that should help you start out with your project. Its not exhaustive and we'll try to update it if we find a really useful function.

First thing to note is that color is 16-bit, and that includes Red, Green and Blue in a 16-bit variable. The way the color is packed in is the top 5 bits are red, the middle 6 bits are green and the bottom 5 bits are blue.

For solid colors, we have this handy cheat-sheet. Of course, you can pick any of 262,000 colors but while starting out, this might be helpful.
Download: file
// Color definitions
#define BLACK           0x0000
#define BLUE            0x001F
#define RED             0xF800
#define GREEN           0x07E0
#define CYAN            0x07FF
#define MAGENTA         0xF81F
#define YELLOW          0xFFE0 
 
#define WHITE           0xFFFF
The Adafruit GFX library is what draws all the dots, lines, shapes, and text. Its fairly detailed and has lots of cool stuff, for lots of info, check out http://learn.adafruit.com/adafruit-gfx-graphics-library

Here is a basic introduction to the GFX lib, it doesn't cover everything but it shows you what some of the most popular shapes look like

First up is the most basic pixel pusher. You can call this with two coordinates and a color and it will make a dot:

Download: file
void drawPixel(uint16_t x, uint16_t y, uint16_t color);
You can also draw lines, with a starting and end point and color.
Download: file
void drawLine(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1, uint16_t color);
If your lines are vertical or horizontal, you can call an optimized drawing function that doesn't do all the angular calculations.
Download: file
void drawVerticalLine(uint16_t x0, uint16_t y0, uint16_t length, uint16_t color);
 
void drawHorizontalLine(uint16_t x0, uint16_t y0, uint16_t length, uint16_t color);
Next up, rectangles and squares can be drawn and filled using the following procedures. If you want a recangle that has a contrasting outline color, fillRect first, then drawRect over it.
Download: file
void drawRect(uint16_t x0, uint16_t y0, uint16_t w, uint16_t h, uint16_t color);
 
void fillRect(uint16_t x0, uint16_t y0, uint16_t w, uint16_t h, uint16_t color);
Likewise, for circles, you can draw and fill.
Download: file
void drawCircle(uint16_t x0, uint16_t y0, uint16_t r,	uint16_t color);
 
void fillCircle(uint16_t x0, uint16_t y0, uint16_t r,	uint16_t color);
Text is a little different. Instead of one procedure, you will set up the text size, color and location and then print() (just like Serial.print()!)
Download: file
void setCursor(uint16_t x0, uint16_t y0);
void setTextColor(uint16_t color);
 
void setTextSize(uint8_t size);
First start with setCursor(x, y) this will place the top right corner of the text where-ever you please. Initially, its set to (0, 0). Then set the text color with setTextColor(color) by default its white. Then set the 'size' with setTextSize(size) this will 'multiply' the text by a scaling factor. Above you can see scales of 1 (default), 2 and 3. This is because we only ship the library with a simple font, to save space. You can just scale it to get bigger text without requiring a new font.

Finally, you can use print() or println() just like you do with Serial! For example, to print a string, use print("Hello world") - that's the first line of the image above. To print variables, you can also use print() the second line isprint(1234.56) and the third line is print(0xDEADBEEF, HEX).

You can also rotate your drawing. Note that this will not rotate what you already drew, but it will relocate any new drawing.
Download: file
 void rotate(uint8_t rotation);
The rotation variable can be 0, 1, 2 or 3. Rotation 0 makes it so that the display is in portrait mode, with the USB jack in the top right. Rotation 2 is portrait, with the USB jack in the bottom left. Rotation 1 is landscape mode, with the USB jack in the bottom right and rotation 3 is also landscape, with the USB jack in the top left.

When you rotate, the origin point moves with you. You may need to reference the size of the screen, which changes between portrait and landscape, use width() and height()! To get the size.
Download: file
uint16_t width(); 
uint16_t height();
These primitives should get you started!
This guide was first published on Dec 17, 2012. It was last updated on Dec 17, 2012. This page (Graphics Library) was last updated on Feb 26, 2020.