Arduino LovyanGFX Cheat Sheet
LovyanGFX: A Powerful Arduino Graphics Library
LovyanGFX is a versatile and efficient graphics library designed for embedded systems, especially microcontrollers like ESP32 and ESP8266. It builds upon and significantly extends the capabilities of the popular Adafruit GFX library, offering numerous enhancements and features for creating visually rich and interactive user interfaces.
Key Features and Advantages of LovyanGFX:
- Extensive Hardware Support: LovyanGFX boasts a wide range of support for various displays, including TFT LCDs, OLEDs, e-paper displays (EPDs), and even some LED matrix panels. It's continuously expanding its compatibility list, ensuring a suitable option for your project.
- High Performance: Optimized for speed and efficiency, LovyanGFX utilizes hardware acceleration whenever possible, enabling smooth animations and fast screen updates, crucial for resource-constrained microcontrollers.
- Rich Drawing Capabilities: It provides a comprehensive set of drawing functions for primitives like lines, circles, rectangles, triangles, as well as more advanced features like Bezier curves, arcs, and filled shapes.
- Advanced Text Rendering: LovyanGFX supports multiple font formats, including standard Adafruit GFX fonts, proportionally spaced fonts, and even Japanese, Chinese, and Korean fonts. It allows for flexible text styling with options for size, color, alignment, and wrapping.
- Sprite Support: The library facilitates the use of sprites (offscreen buffers) for complex graphics and animations, allowing for efficient rendering and manipulation of graphical elements without redrawing the entire screen.
- Image Handling: LovyanGFX supports various image formats, including BMP, JPG, and PNG, allowing for direct rendering of images from files or memory.
- Touchscreen Integration: It seamlessly integrates with various touch controllers, enabling the creation of interactive interfaces with touch input.
- Built-in Auto-Detection: For many popular development boards, LovyanGFX can automatically detect the connected display and configure itself accordingly, simplifying the setup process.
- Active Community and Development: The library is actively maintained and developed, with a vibrant community contributing to its growth and providing support.
Below is a breakdown of the LovyanGFX library commands, grouped by functionality, with specific code examples.
LovyanGFX Cheat Sheet
1. Initialization & Configuration
| Command | Description | Example |
|---|---|---|
#include <LovyanGFX.hpp> |
Includes the LovyanGFX library | #include <LovyanGFX.hpp> |
#define LGFX_AUTODETECT |
Auto-detects the display type (excluding some like D-duino-32 XS, WT32-SC01, PyBadge) | #define LGFX_AUTODETECT |
#define LGFX_... |
Defines the specific display type (if not using auto-detection) | #define LGFX_M5STACK_CORE2 |
static LGFX lcd; |
Creates an instance of the LGFX class | static LGFX lcd; |
lcd.init(); |
Initializes the display | lcd.init(); |
lcd.setRotation(n); |
Rotates the display (n = 0-3, 4-7 inverts) | lcd.setRotation(1); // Rotate 90 degrees clockwise |
lcd.setBrightness(n); |
Adjusts the display brightness (n = 0-255) | lcd.setBrightness(128); // Set brightness to half |
lcd.setColorDepth(n); |
Sets the color depth (n = 1, 2, 4, 8, 16, 24) | lcd.setColorDepth(16); // Set color depth to RGB565 |
lcd.setSwapBytes(b); |
Sets the byte swap mode (b = true/false) | lcd.setSwapBytes(true); // Enable byte swapping |
display.calibrateTouch(…); |
Calibrates the touch screen (if available) | display.calibrateTouch(nullptr, TFT_WHITE, TFT_BLACK, display.width() >> 3); |
lcd.setBaseColor(color); |
Sets the base color of the display | lcd.setBaseColor(TFT_BLACK); // Set base color to black |
2. Drawing Basic Shapes
| Command | Description | Example |
|---|---|---|
lcd.fillScreen(color); |
Fills the entire screen with color |
lcd.fillScreen(TFT_RED); // Fill screen with red |
lcd.clear(color); |
Clears the screen with the base color color |
lcd.clear(TFT_GREEN); // Clear screen with green as the base color |
lcd.drawPixel(x, y, color); |
Draws a pixel at coordinates (x, y) with color |
lcd.drawPixel(10, 20, TFT_BLUE); // Draw a blue pixel at (10, 20) |
lcd.drawFastVLine(…); |
Draws a vertical line | lcd.drawFastVLine(50, 30, 40, TFT_WHITE); // White vertical line at x=50, y=30 |
lcd.drawFastHLine(…); |
Draws a horizontal line | lcd.drawFastHLine(30, 50, 40, TFT_YELLOW); // Yellow horizontal line |
lcd.drawRect(…); |
Draws a rectangle | lcd.drawRect(10, 10, 50, 30, TFT_CYAN); // Cyan rectangle outline |
lcd.fillRect(…); |
Fills a rectangle | lcd.fillRect(60, 10, 50, 30, TFT_MAGENTA); // Filled magenta rectangle |
lcd.drawRoundRect(…); |
Draws a rounded rectangle | lcd.drawRoundRect(10, 50, 50, 30, 5, TFT_ORANGE); // Rounded rectangle |
lcd.fillRoundRect(…); |
Fills a rounded rectangle | lcd.fillRoundRect(60, 50, 50, 30, 5, TFT_PINK); // Filled rounded rectangle |
lcd.drawCircle(…); |
Draws a circle | lcd.drawCircle(80, 80, 20, TFT_WHITE); // White circle outline |
lcd.fillCircle(…); |
Fills a circle | lcd.fillCircle(160, 80, 20, TFT_DARKGREY); // Filled dark grey circle |
lcd.drawEllipse(…); |
Draws an ellipse | lcd.drawEllipse(80, 160, 30, 15, TFT_RED); // Red ellipse outline |
lcd.fillEllipse(…); |
Fills an ellipse | lcd.fillEllipse(160, 160, 30, 15, TFT_GREEN); // Filled green ellipse |
lcd.drawLine(…); |
Draws a line | lcd.drawLine(10, 200, 200, 230, TFT_BLUE); // Blue line |
lcd.drawTriangle(…); |
Draws a triangle | lcd.drawTriangle(210, 200, 250, 200, 230, 230, TFT_YELLOW); // Yellow triangle |
lcd.fillTriangle(…); |
Fills a triangle | lcd.fillTriangle(260, 200, 300, 200, 280, 230, TFT_CYAN); // Filled cyan triangle |
lcd.drawBezier(…); |
Draws a Bezier curve | lcd.drawBezier(10, 240, 50, 280, 90, 240, TFT_MAGENTA); // Magenta Bezier curve |
lcd.drawArc(…); |
Draws an arc | lcd.drawArc(160, 240, 30, 20, 0, 120, TFT_ORANGE); // Orange arc |
lcd.fillArc(…); |
Fills an arc | lcd.fillArc(240, 240, 30, 20, 0, 120, TFT_PINK); // Filled pink arc |
lcd.drawGradientLine(…); |
Draws a line with a color gradient | lcd.drawGradientLine(10, 280, 100, 310, TFT_RED, TFT_BLUE); // Gradient line |
3. Displaying Text
| Command | Description | Example |
|---|---|---|
lcd.setCursor(x, y); |
Sets the cursor position for print functions |
lcd.setCursor(10, 10); // Set cursor to (10, 10) |
lcd.print(…); |
Prints text or numbers | lcd.print("Hello World!"); // Print "Hello World!" at the current cursor position |
lcd.println(…); |
Prints text or numbers and adds a newline | lcd.println(123); // Print "123" and move the cursor to the next line |
lcd.printf(…); |
Prints formatted text (similar to printf in C) |
lcd.printf("Value: %d", 456); // Print "Value: 456" |
lcd.drawString(…); |
Draws a string at the specified position | lcd.drawString("LovyanGFX", 50, 50); // Draw "LovyanGFX" at (50, 50) |
lcd.drawNumber(…); |
Draws a number at the specified position | lcd.drawNumber(789, 100, 50); // Draw "789" at (100, 50) |
lcd.drawFloat(…); |
Draws a floating-point number at the specified position | lcd.drawFloat(3.14159, 4, 150, 50); // Draw "3.1415" at (150, 50) |
lcd.setFont(…); |
Sets the font | lcd.setFont(&fonts::FreeSansBold9pt7b); // Set the font to FreeSansBold9pt7b |
lcd.setTextFont(n); |
Sets the font by number (TFT_eSPI compatibility, not recommended) | lcd.setTextFont(2); // Set the font to Font2 (TFT_eSPI compatibility) |
lcd.setTextColor(fg, bg); |
Sets the text color and background color | lcd.setTextColor(TFT_WHITE, TFT_BLUE); // Set text color to white and background color to blue |
lcd.setTextDatum(…); |
Sets the text anchor point (alignment) | lcd.setTextDatum(textdatum_t::middle_center); // Center the text horizontally and vertically |
lcd.setTextSize(x, y); |
Sets the text size (x: horizontal scaling, y: vertical scaling) | lcd.setTextSize(2, 3); // Double the width and triple the height of the text |
lcd.setTextWrap(b); |
Sets text wrapping (b = true/false) | lcd.setTextWrap(true); // Enable text wrapping |
lcd.setTextWrap(b1, b2); |
Sets text wrapping and vertical scrolling (b1: horizontal wrap, b2: vertical scroll) | lcd.setTextWrap(true, true); // Enable text wrapping and vertical scrolling |
lcd.setTextScroll(b); |
Enables/disables text scrolling (b = true/false) | lcd.setTextScroll(true); // Enable text scrolling |
lcd.setTextPadding(n); |
Sets the minimum width when filling the background for text | lcd.setTextPadding(100); // Set the minimum width to 100 pixels when filling the background for text |
4. Sprites (Offscreen Buffer)
| Command | Description | Example |
|---|---|---|
static LGFX_Sprite sprite(&lcd); |
Creates an instance of the LGFX_Sprite class | static LGFX_Sprite sprite(&lcd); |
sprite.createSprite(w, h); |
Creates a sprite with width w and height h |
sprite.createSprite(64, 64); // Create a 64x64 pixel sprite |
sprite.deleteSprite(); |
Deletes the sprite and frees its memory | sprite.deleteSprite(); // Delete the sprite |
sprite.pushSprite(x, y, transp); |
Draws the sprite at coordinates (x, y) on the main screen, transp is the transparent color (optional) |
sprite.pushSprite(10, 20); // Draw the sprite at (10, 20) |
sprite.pushRotateZoom(…); |
Draws the sprite with rotation and zoom | sprite.pushRotateZoom(160, 120, 45, 2.0, 1.5); // Rotate 45 degrees, zoom 2x1.5 |
sprite.setPivot(x, y); |
Sets the pivot point for rotation and zoom | sprite.setPivot(32, 32); // Set the pivot point to the center of the sprite |
sprite.setPaletteColor(…); |
Sets the color for a palette entry in indexed color mode | sprite.setPaletteColor(1, TFT_RED); // Set palette entry 1 to red |
5. Displaying Images
| Command | Description | Example |
|---|---|---|
lcd.setAddrWindow(x, y, w, h); |
Sets the address window for drawing an image, starting at coordinates (x, y) with width w and height h |
lcd.setAddrWindow(0, 0, 128, 64); // Set the address window for a 128x64 image |
lcd.setWindow(x0, y0, x1, y1); |
Sets the address window for drawing an image, from top-left coordinates (x0, y0) to bottom-right coordinates (x1, y1) | lcd.setWindow(10, 20, 138, 84); // Set the address window for a 128x64 image starting at (10, 20) |
lcd.writePixels(data, len, swap); |
Writes image data data with length len pixels, swap indicates whether byte swapping is needed (true/false). Requires startWrite() before and endWrite() after using this function. |
lcd.writePixels(myImageData, 128 * 64, true); // Write image data with byte swapping |
lcd.pushPixels(data, len, swap); |
Writes image data data with length len pixels, swap indicates whether byte swapping is needed (true/false). Does not require startWrite() and endWrite() when using this function. |
lcd.pushPixels(myImageData, 128 * 64, true); // Write image data with byte swapping |
lcd.pushImage(x, y, w, h, data, transp); |
Draws an image at coordinates (x, y) with width w, height h, data data, and transparent color transp (optional) |
lcd.pushImage(10, 20, 128, 64, myImageData, TFT_BLACK); // Draw an image with black as the transparent color |
lcd.pushImageRotateZoom(…); |
Draws an image with rotation and zoom | lcd.pushImageRotateZoom(160, 120, 64, 32, 45, 2.0, 1.5, 128, 64, myImageData); // Rotate 45 degrees, zoom 2x1.5 |
lcd.pushImageRotateZoomWithAA(…); |
Draws an image with rotation, zoom, and anti-aliasing | lcd.pushImageRotateZoomWithAA(160, 120, 64, 32, 45, 2.0, 1.5, 128, 64, myImageData); // Rotate 45 degrees, zoom 2x1.5 with anti-aliasing |
lcd.pushImageAffine(…); |
Draws an image with affine transformation | float matrix[6] = { 1.0, 0.0, 160, 0.0, 1.0, 120 }; lcd.pushImageAffine(matrix, 128, 64, myImageData); // Draw an image with affine transformation |
lcd.pushImageAffineWithAA(…); |
Draws an image with affine transformation and anti-aliasing | float matrix[6] = { 1.0, 0.0, 160, 0.0, 1.0, 120 }; lcd.pushImageAffineWithAA(matrix, 128, 64, myImageData); // Draw an image with affine transformation and anti-aliasing |
6. SPI Control
| Command | Description | Example |
|---|---|---|
lcd.startWrite(); |
Starts SPI communication (holds the SPI bus) | lcd.startWrite(); // Start SPI communication |
lcd.endWrite(); |
Ends SPI communication (releases the SPI bus) | lcd.endWrite(); // End SPI communication |
lcd.writePixel(x, y, color); |
Writes a pixel at coordinates (x, y) with color. Requires startWrite() before using this function. |
lcd.writePixel(10, 20, TFT_RED); // Write a red pixel at (10, 20) |
lcd.writeFastVLine(…); |
Writes a vertical line. Requires startWrite() before using this function. |
lcd.writeFastVLine(50, 30, 40, TFT_WHITE); // Write a white vertical line |
lcd.writeFastHLine(…); |
Writes a horizontal line. Requires startWrite() before using this function. |
lcd.writeFastHLine(30, 50, 40, TFT_YELLOW); // Write a yellow horizontal line |
lcd.writeFillRect(…); |
Fills a rectangle. Requires startWrite() before using this function. |
lcd.writeFillRect(10, 10, 50, 30, TFT_BLUE); // Fill a blue rectangle |
lcd.endTransaction(); |
Forces the end of SPI communication (releases the SPI bus) regardless of the number of startWrite() calls |
lcd.endTransaction(); // Force end of SPI communication |
lcd.beginTransaction(); |
Forces the start of SPI communication (holds the SPI bus) regardless of the number of endWrite() calls |
lcd.beginTransaction(); // Force start of SPI communication |
7. Other
| Command | Description | Example |
|---|---|---|
lcd.color888(…); |
Creates a 24-bit RGB888 color code | lcd.color888(255, 0, 0); // Red |
lcd.color565(…); |
Creates a 16-bit RGB565 color code | lcd.color565(0, 255, 0); // Green |
lcd.color332(…); |
Creates an 8-bit RGB332 color code | lcd.color332(0, 0, 255); // Blue |
lcd.setColor(…); |
Sets the current drawing color (used for drawing functions without a color parameter) | lcd.setColor(TFT_CYAN); // Set the drawing color to cyan |
lcd.setClipRect(…); |
Sets a clipping rectangle for drawing | lcd.setClipRect(10, 10, 100, 50); // Limit drawing to a 100x50 rectangle at (10, 10) |
lcd.clearClipRect(); |
Clears the clipping rectangle | lcd.clearClipRect(); // Remove the clipping rectangle |
lcd.setScrollRect(…); |
Sets the scrolling rectangle for text | lcd.setScrollRect(0, 50, 128, 100, TFT_BLACK); // Set the scrolling rectangle |
lcd.clearScrollRect(); |
Clears the scrolling rectangle | lcd.clearScrollRect(); // Clear the scrolling rectangle |
lcd.getTouch(…); |
Gets the touch coordinates | int32_t x, y; if (lcd.getTouch(&x, &y)) { ... } |
lcd.width(); |
Gets the width of the display | int width = lcd.width(); |
lcd.height(); |
Gets the height of the display | int height = lcd.height(); |
lcd.isEPD(); |
Checks if the display is an e-paper display | if (lcd.isEPD()) { ... } |
Note:
- This is just a selection of commonly used commands. The LovyanGFX library has many more functionalities.
- Refer to the library documentation for more details on each command and its usage.
I hope this detailed explanation with specific code examples helps you better understand and utilize the LovyanGFX library!