Display — Images

M5GFX source: lgfx/v1/LGFXBase.hpp
Back to: Display overview

Load and display bitmap, BMP, JPEG, and PNG images from memory buffers or SD card files.

---

drawBitmap() — 1-bit Bitmap

void drawBitmap(int32_t x, int32_t y, const uint8_t* bitmap,
                int32_t w, int32_t h, uint16_t color);

void drawBitmap(int32_t x, int32_t y, const uint8_t* bitmap,
                int32_t w, int32_t h, uint16_t fg, uint16_t bg);

Draws a 1-bit-per-pixel bitmap. Each bit represents one pixel.

Parameter	Type	Description
x, y	int32_t	Top-left position
bitmap	const uint8_t*	Bitmap data (1bpp)
w, h	int32_t	Width and height in pixels
color / fg	uint16_t	Foreground color for set bits
bg	uint16_t	Background color for clear bits

// 8x8 heart icon (1bpp)
static const uint8_t heart[8] = {
    0b00000000,
    0b01100110,
    0b11111111,
    0b11111111,
    0b01111110,
    0b00111100,
    0b00011000,
    0b00000000
};
M5Cardputer.Display.drawBitmap(10, 10, heart, 8, 8, TFT_RED);

---

pushImage() — Raw Pixel Array

void pushImage(int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t* data);
void pushImage(int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t* data, uint16_t transparent);

Blits a raw 16-bit RGB565 pixel array to the display. The transparent color variant skips pixels matching transparent.

Parameter	Type	Description
x, y	int32_t	Top-left position
w, h	int32_t	Image dimensions
data	const uint16_t*	RGB565 pixel array (row-major)
transparent	uint16_t	Color to treat as transparent

// 16x16 sprite (RGB565, row-major)
static const uint16_t sprite[] = {
    0x0000, 0x0000, 0xF800, 0xF800, ...
    // ... 16 rows of 16 pixels
};
M5Cardputer.Display.pushImage(50, 50, 16, 16, sprite);

// With transparency (TFT_BLACK pixels are invisible)
M5Cardputer.Display.pushImage(50, 50, 16, 16, sprite, TFT_BLACK);

---

drawBmp() — BMP from Memory

bool drawBmp(const uint8_t* data, uint32_t len,
             int32_t x = 0, int32_t y = 0,
             int32_t maxWidth = 0, int32_t maxHeight = 0,
             int32_t offX = 0, int32_t offY = 0,
             float scaleX = 1.0f, float scaleY = 0.0f);

Draws a BMP image from a memory buffer.

Parameter	Type	Default	Description
data	const uint8_t*	—	BMP file data in memory
len	uint32_t	—	Data length in bytes
x, y	int32_t	0	Top-left position
maxWidth	int32_t	0	Max output width (0 = actual)
maxHeight	int32_t	0	Max output height (0 = actual)
offX, offY	int32_t	0	Source crop offset
scaleX	float	1.0	Horizontal scale
scaleY	float	0.0	Vertical scale (0 = same as scaleX)

Returns true on success.

// Embedded BMP data
extern const uint8_t logo_bmp[] asm("_binary_logo_bmp_start");
M5Cardputer.Display.drawBmp(logo_bmp, 0, 10, 10);

---

drawBmpFile() — BMP from SD

bool drawBmpFile(const char* path,
                 int32_t x = 0, int32_t y = 0,
                 int32_t maxWidth = 0, int32_t maxHeight = 0,
                 int32_t offX = 0, int32_t offY = 0,
                 float scaleX = 1.0f, float scaleY = 0.0f);

Draws a BMP file from SD card. Parameters same as drawBmp().

M5Cardputer.Display.drawBmpFile("/logo.bmp", 10, 10);
M5Cardputer.Display.drawBmpFile("/icon.bmp", 0, 0, 64, 64);  // Scaled to 64x64

---

drawJpg() / drawJpgFile() — JPEG from Memory / SD

bool drawJpg(const uint8_t* data, uint32_t len,
             int32_t x = 0, int32_t y = 0,
             int32_t maxWidth = 0, int32_t maxHeight = 0,
             int32_t offX = 0, int32_t offY = 0,
             float scaleX = 1.0f, float scaleY = 0.0f);

bool drawJpgFile(const char* path,
                 int32_t x = 0, int32_t y = 0,
                 int32_t maxWidth = 0, int32_t maxHeight = 0,
                 int32_t offX = 0, int32_t offY = 0,
                 float scaleX = 1.0f, float scaleY = 0.0f);

Decodes and draws a JPEG image. Parameters same as drawBmp().

// Full-screen JPEG background from SD
M5Cardputer.Display.drawJpgFile("/bg.jpg", 0, 0, 320, 240);

// Thumbnail at 64x64
M5Cardputer.Display.drawJpgFile("/photo.jpg", 10, 10, 64, 64, 0, 0, 1.0f);

---

drawPng() / drawPngFile() — PNG from Memory / SD

bool drawPng(const uint8_t* data, uint32_t len,
             int32_t x = 0, int32_t y = 0,
             int32_t maxWidth = 0, int32_t maxHeight = 0,
             int32_t offX = 0, int32_t offY = 0,
             float scaleX = 1.0f, float scaleY = 0.0f);

bool drawPngFile(const char* path,
                 int32_t x = 0, int32_t y = 0,
                 int32_t maxWidth = 0, int32_t maxHeight = 0,
                 int32_t offX = 0, int32_t offY = 0,
                 float scaleX = 1.0f, float scaleY = 0.0f);

Decodes and draws a PNG image (supports transparency). Parameters same as drawBmp().

// PNG with transparent background
M5Cardputer.Display.fillScreen(TFT_BLACK);
M5Cardputer.Display.drawPngFile("/icon.png", 100, 50);

// Scaled PNG
M5Cardputer.Display.drawPngFile("/logo.png", 0, 0, 128, 128);

---

Complete Example: Image Gallery

#include <SD.h>
#include <SPI.h>

void initSD() {
    SPI.begin(40, 39, 14, 12);
    SD.begin(12, SPI, 25000000);
}

void drawAllImages() {
    auto& d = M5Cardputer.Display;
    d.fillScreen(TFT_BLACK);

    // JPEG background
    d.drawJpgFile("/bg.jpg", 0, 0, 320, 240);
    delay(1000);

    // BMP logo
    d.fillScreen(TFT_BLACK);
    d.drawBmpFile("/logo.bmp", 50, 50);
    delay(1000);

    // PNG icon with transparency
    d.fillScreen(TFT_NAVY);
    d.drawPngFile("/icon.png", 128, 80);
}