显示屏 — 图片

M5GFX 源码： lgfx/v1/LGFXBase.hpp
返回： 显示屏概览

从内存缓冲区或 SD 卡加载并显示位图、BMP、JPEG 和 PNG 图片。

---

drawBitmap() — 1 位位图

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);

绘制 1 位每像素位图。每个 bit 代表一个像素。

参数	类型	说明
x, y	int32_t	左上角位置
bitmap	const uint8_t*	位图数据（1bpp）
w, h	int32_t	宽高（像素）
color / fg	uint16_t	置位像素的前景色
bg	uint16_t	清零像素的背景色

// 8x8 心形图标（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() — 原始像素数组

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);

将原始 16 位 RGB565 像素数组传送到显示屏。透明色变体跳过匹配 transparent 的像素。

参数	类型	说明
x, y	int32_t	左上角位置
w, h	int32_t	图片尺寸
data	const uint16_t*	RGB565 像素数组（行主序）
transparent	uint16_t	视为透明的颜色

// 16x16 精灵图（RGB565，行主序）
static const uint16_t sprite[] = {
    0x0000, 0x0000, 0xF800, 0xF800, ...
    // ... 16 行，每行 16 个像素
};
M5Cardputer.Display.pushImage(50, 50, 16, 16, sprite);

// 带透明色（TFT_BLACK 像素不可见）
M5Cardputer.Display.pushImage(50, 50, 16, 16, sprite, TFT_BLACK);

---

drawBmp() — 从内存绘制 BMP

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);

从内存缓冲区绘制 BMP 图片。

参数	类型	默认	说明
data	const uint8_t*	—	内存中的 BMP 数据
len	uint32_t	—	数据长度（字节）
x, y	int32_t	0	左上角位置
maxWidth	int32_t	0	最大输出宽度（0 = 实际）
maxHeight	int32_t	0	最大输出高度（0 = 实际）
offX, offY	int32_t	0	源图裁剪偏移
scaleX	float	1.0	水平缩放
scaleY	float	0.0	垂直缩放（0 = 同 scaleX）

成功返回 true。

// 嵌入的 BMP 数据
extern const uint8_t logo_bmp[] asm("_binary_logo_bmp_start");
M5Cardputer.Display.drawBmp(logo_bmp, 0, 10, 10);

---

drawBmpFile() — 从 SD 卡绘制 BMP

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);

从 SD 卡绘制 BMP 文件。参数同 drawBmp()。

M5Cardputer.Display.drawBmpFile("/logo.bmp", 10, 10);
M5Cardputer.Display.drawBmpFile("/icon.bmp", 0, 0, 64, 64);  // 缩放至 64x64

---

drawJpg() / drawJpgFile() — 从内存 / SD 卡绘制 JPEG

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);

解码并绘制 JPEG 图片。参数同 drawBmp()。

// 从 SD 卡绘制全屏 JPEG 背景
M5Cardputer.Display.drawJpgFile("/bg.jpg", 0, 0, 320, 240);

// 64x64 缩略图
M5Cardputer.Display.drawJpgFile("/photo.jpg", 10, 10, 64, 64);

---

drawPng() / drawPngFile() — 从内存 / SD 卡绘制 PNG

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);

解码并绘制 PNG 图片（支持透明度）。参数同 drawBmp()。

// 带透明背景的 PNG
M5Cardputer.Display.fillScreen(TFT_BLACK);
M5Cardputer.Display.drawPngFile("/icon.png", 100, 50);

// 缩放的 PNG
M5Cardputer.Display.drawPngFile("/logo.png", 0, 0, 128, 128);

---

完整示例：图片画廊

#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 背景
    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 图标
    d.fillScreen(TFT_NAVY);
    d.drawPngFile("/icon.png", 128, 80);
}