Sprite Management

Panel Parameters
- isEPD
- height
- width
- popState
- pushState
- setBrightness
- getBrightness
- setEpdMode
- getEpdMode
- setResolution
- setRotation
- getRotation
Color
Clear Screen
Coordinate Point Setting
- setCursor
- getCursorX
- getCursorY
- setPivot
- getPivotX
- getPivotY
Sprite Area Selection
Sprite Scrolling
Custom Processing
- effect

Panel Parameters

isEPD

Function Prototype:

bool isEPD(void) 

Description:

Check if the panel is EPD

Return:

bool: EPD status
- true: is EPD
- false: not EPD

height

Function Prototype:

int32_t height(void) 

Description:

Get the current panel height

Parameters:

null

Return:

int32_t: current panel pixel height

width

Function Prototype:

int32_t width (void) 

Description:

Get the current panel width

Parameters:

null

Return:

int32_t: current panel pixel width

popState

Function Prototype:

void popState(void) 

Description:

Temporarily save display attribute information, such as text font, cursor position, etc. The restore operation is performed by pushState.

Parameters:

null

Return:

null

pushState

Function Prototype:

void pushState(void) 

Description:

Restore the display attribute information previously saved by popState

Parameters:

null

Return:

null

setBrightness

Function Prototype:

void setBrightness(uint8_t brightness) 

Description:

Set the brightness of the display panel

Parameters:

brightness: specified brightness value (0-255)

Return:

null

getBrightness

Function Prototype:

uint8_t getBrightness(void) 

Description:

Get the brightness set by setBrightness

Parameters:

null

Return:

uint8_t: brightness value

setEpdMode

Function Prototype:

void setEpdMode(epd_mode_t epd_mode) 

Description:

Set EPD mode

Parameters:

epd_mode: specified EPD mode

Return:

null

getEpdMode

Function Prototype:

epd_mode_t getEpdMode(void) 

Description:

Get the EPD mode set by setEpdMode. (Only for e-paper products)

Parameters:

null

Return:

epd_mode_t: EPD mode value (about epd_mode_t)

setResolution

Function Prototype 1:

bool setResolution(uint16_t logical_width = 0, uint16_t logical_height = 0, float refresh_rate = 0.0f, uint16_t output_width = 0, uint16_t output_height = 0, uint_fast8_t scale_w = 0, uint_fast8_t scale_h = 0, uint32_t pixel_clock = 74250000) 

Function Prototype 2:

bool setResolution( const config_resolution_t& cfg_resolution ) 

Description:

Set resolution, only applicable to M5AtomDisplay.

Parameters:

logical_width: logical width
logical_height: logical height
refresh_rate: refresh rate
output_width: output width
output_height: output height
scale_w: scale factor width
scale_h: scale factor height
pixel_clock: pixel clock frequency
cfg_resolution: resolution configuration struct

Note:

cfg_resolution contains all the parameters listed above.

Return:

bool
- true: set resolution succeeded
- false: set resolution failed

setRotation

Function Prototype:

void setRotation(uint_fast8_t r) 

Description:

Set display rotation angle

Parameters:

r: rotation angle (0-7)

Return:

null

Note:

1. The rotation angle is a multiple of 90°.
2. 0 to 3 means clockwise rotation, 4 to 7 means counterclockwise rotation (default is 1).
3. The rotation angle needs to be set before display.

getRotation

Function Prototype:

uint8_t getRotation(void) 

Description:

Get the rotation value set by setRotation

Parameters:

null

Return:

uint8_t: current rotation value
- 0: 0 degrees
- 1: 90 degrees
- 2: 180 degrees
- 3: 270 degrees
- 4: -0 degrees
- 5: -90 degrees
- 6: -180 degrees
- 7: -270 degrees

Color

setBaseColor

Function Prototype:

void setBaseColor(T c) 

Description:

Set the base color, which can be specified as the color outside the drawing area when using the scrolling function.

Parameters:

c: specified base color

Return:

null

Note:

1. The base color is usually used for filling the area outside the scrolling region.
2. The value of the base color can be RGB or other color formats, depending on the panel's color depth and configuration.

getBaseColor

Function Prototype:

uint32_t getBaseColor(void) 

Description:

Get the base color set by setBaseColor

Parameters:

null

Return:

uint32_t: base color value

setColor

Function Prototype 1:

void setColor(uint8_t r, uint8_t g, uint8_t b) 

Function Prototype 2:

void setColor(T color) 

Description:

Set the drawing fill color. For example, when fillCircle and other functions do not specify a color parameter, the color set by this function will be used to fill the circle.

Parameters:

r: red component (0-255)
g: green component (0-255)
b: blue component (0-255)
color: color code

Return:

null

setRawColor

Function Prototype:

void setRawColor(uint32_t c) 

Description:

Set the raw color value, suitable for scenarios where RGB color codes are used directly.

Parameters:

c: color code

Return:

null

getRawColor

Function Prototype:

uint32_t getRawColor(void) 

Description:

Get the raw color value set by setRawColor

Parameters:

null

Return:

uint32_t: raw color value

setColorDepth

Function Prototype 1:

void setColorDepth(uint8_t bpp) 

Function Prototype 2:

void* setColorDepth(color_depth_t depth) 

Description:

Set color depth

Parameters:

bpp: bits per pixel
- 1: 1 bit
- 2: 2 bits
- 4: 4 bits
- 8: 8 bits
- 16: 16 bits
- 24: 24 bits
- 32: 32 bits
depth: color depth (about color_depth_t)

Note:

If using palette or e-paper products, the maximum color depth is 8 bits.

getColorDepth

Function Prototype:

color_depth_t getColorDepth(void) 

Description:

Get the color depth set by setColorDepth

Parameters:

null

Return:

color_depth_t: color depth value

getPalette

Function Prototype:

RGBColor* getPalette(void) 

Description:

Get the current palette information

Parameters:

null

Return:

RGBColor*: pointer to the bgr888_t struct, pointing to the first color in the current palette

getPaletteCount

Function Prototype:

uint32_t getPaletteCount(void) 

Description:

Get the number of colors in the palette

Parameters:

null

Return:

uint32_t: number of colors in the palette

Clear Screen

clear

Function Prototype:

void clear(const T &color) 

Description

Clear the display. If a color is specified, initialize the screen with that color. The effect is the same as clearDisplay and fillScreen.

Parameters:

color: clear screen color (about color code)

Return:

null

clearDisplay

Function Prototype:

void clearDisplay(uint32_t color = 0) 

Description:

Clear the display. If a color is specified, initialize the screen with that color, otherwise use the default color. The effect is the same as fillScreen and clear.

Parameters:

color: clear screen color (about color code)

Return:

null

fillScreen

Function Prototype:

void fillScreen(const T &color) 

Description:

Clear the display. If a color is specified, initialize the screen with that color. The effect is the same as clear and clearDisplay.

Parameters:

color: fill color

Return:

null

Coordinate Point Setting

setCursor

Function Prototype 1:

void setCursor(int16_t x, int16_t y) 

Function Prototype 2:

void setCursor(int16_t x, int16_t y, uint8_t font)
void setCursor( int32_t x, int32_t y, const IFont* font) 

Description:

Set the cursor position

Parameters:

x: cursor x coordinate
y: cursor y coordinate
font: text font format

Return:

null

getCursorX

Function Prototype:

int32_t getCursorX(void) 

Description:

Get the current x coordinate position of the cursor

Parameters:

null

Return:

int32_t: current x coordinate position of the cursor

getCursorY

Function Prototype:

int32_t getCursorY(void) 

Description:

Get the current y coordinate position of the cursor

Parameters:

null

Return:

int32_t: current y coordinate position of the cursor

setPivot

Function Prototype:

void setPivot(float x, float y) 

Description:

Set the reference point coordinates

Parameters:

x: reference point x coordinate
y: reference point y coordinate

Return:

null

getPivotX

Function Prototype:

float getPivotX(void) 

Description:

Get the center point coordinate of the x axis

Parameters:

null

Return:

float: center point coordinate of the x axis

getPivotY

Function Prototype:

float getPivotY(void) 

Description:

Get the center point coordinate of the y axis

Parameters:

null

Return:

float: center point coordinate of the y axis

Sprite Area Selection

setAddrWindow

Function Prototype:

void setAddrWindow(int32_t x, int32_t y, int32_t w, int32_t h) 

Description:

Specify the rectangular range for operations such as writePixels and pushPixels

Note:

The function is the same as setWindow, but the parameters are different. setAddrWindow checks for overflow outside the screen, while setWindow does not.

Parameters:

x: specified x coordinate
y: specified y coordinate
w: specified width
h: specified height

Return:

null

setWindow

Note:

The function is the same as setAddrWindow, but the parameters are different. setAddrWindow checks for overflow outside the screen, while setWindow does not.

Function Prototype:

void setWindow(uint_fast16_t xs, uint_fast16_t ys, uint_fast16_t xe, uint_fast16_t ye) 

Description:

Specify the rectangular range for operations such as writePixels and pushPixels

Parameters:

xs: start point x coordinate
ys: start point y coordinate
xe: end point x coordinate
ye: end point y coordinate

Return:

null

setAddrWindow

Function Prototype:

void setAddrWindow(int32_t x, int32_t y, int32_t w, int32_t h) 

Description:

Specify the rectangular range for operations such as writePixels and pushPixels

Note:

The function is the same as setWindow, but the parameters are different. setAddrWindow checks for overflow outside the screen, while setWindow does not.

Parameters:

x: specified x coordinate
y: specified y coordinate
w: specified width
h: specified height

Return:

null

setWindow

Note:

The function is the same as setAddrWindow, but the parameters are different. setAddrWindow checks for overflow outside the screen, while setWindow does not.

Function Prototype:

void setWindow(uint_fast16_t xs, uint_fast16_t ys, uint_fast16_t xe, uint_fast16_t ye) 

Description:

Specify the rectangular range for operations such as writePixels and pushPixels

Parameters:

xs: start point x coordinate
ys: start point y coordinate
xe: end point x coordinate
ye: end point y coordinate

Return:

null

setClipRect

Function Prototype:

void setClipRect(int32_t x, int32_t y, int32_t w, int32_t h) 

Description:

Specify the clipping rectangle for the drawing area

Parameters:

x: specified x coordinate
y: specified y coordinate
w: specified width
h: specified height

Return:

null

getClipRect

Function Prototype:

void getClipRect(int32_t *x, int32_t *y, int32_t *w, int32_t *h) 

Description:

Get the clipping area set by setClipRect

Parameters:

x: pointer to x coordinate
y: pointer to y coordinate
w: pointer to width
h: pointer to height

Return:

null

clearClipRect

Function Prototype:

void clearClipRect(void) 

Description:

Clear the rectangle drawn by setClipRect

Parameters:

null

Return:

null

Sprite Scrolling

scroll

Function Prototype:

void scroll(int_fast16_t dx, int_fast16_t dy) 

Description:

Scroll the displayed screen

Parameters:

dx: distance to scroll on the X axis
dy: distance to scroll on the Y axis

Return:

null

Example Program:

cpp 
#include <Arduino.h>
#include <M5GFX.h>

M5GFX display;
uint16_t x;
uint16_t y;
bool flag = false;

void setup()
{
    display.begin();
    display.drawString("        Scrolling...      ", 0, 0, &fonts::lgfxJapanGothic_24);
}

void loop()
{
    if(flag)
    {
        for (int i=-53; i<=53; i+=1) {
            display.scroll(0, -2);
            if(i>=53){ flag = false; }
        }
    }
    else
    {
       for (int i=-53; i<=53; i+=1) {
            display.scroll(0, 2);
            if(i>=53){ flag = true; }
        } 
    }
}

setTextScroll

Function Prototype:

void setTextScroll(bool scroll) 

Description:

Set text scrolling

Parameters:

scroll: text scroll flag

Return:

null

setScrollRect

Note:

To set the text scroll area, you must use setTextScroll(true).

Function Prototype:

void setScrollRect(int32_t x, int32_t y, int32_t w, int32_t h, const T& color) 

Description:

Set the text scroll area

Parameters:

x: scroll area start x coordinate
y: scroll area start y coordinate
w: scroll area width
h: scroll area height
color: scroll area color

Return:

null

getScrollRect

Function Prototype:

void getScrollRect(int32_t *x, int32_t *y, int32_t *w, int32_t *h) 

Description:

Get the scroll area set by setScrollRect

Parameters:

x: pointer to x coordinate
y: pointer to y coordinate
w: pointer to width
h: pointer to height

Return:

null

clearScrollRect

Function Prototype:

void clearScrollRect(void) 

Description:

Clear the scroll rectangle drawn by setScrollRect

Parameters:

null

Return:

null

Example Program 1:

cpp 
#include <Arduino.h>
#include <M5GFX.h>

M5GFX display;
uint32_t count = 0;

void setup() {
    display.begin();
    display.setRotation(1);
    if(display.isEPD())
    {
        display.setColorDepth(8);//The ink screen product supports a maximum bit depth of 8 bits.
        display.setEpdMode(epd_fastest);
    }
    else
    {
        display.setColorDepth(16);
    }

    display.fillScreen(TFT_WHITE);
    display.setBaseColor(TFT_WHITE);
    display.setTextFont(&fonts::FreeMonoBoldOblique18pt7b);
    display.setTextColor(TFT_BLACK);
    display.setTextScroll(true);
    display.setScrollRect(0, 0, display.width(), display.height());
}

void loop() {
  display.printf("Scroll: %d\n", count);
  count++;
  delay(500);
}

By comparing the final results of the following two example programs, you can see the advantages of using Canvas.

Example Program 2 (Display):

cpp 
#include <Arduino.h>
#include <M5GFX.h>

M5GFX display;
uint16_t w;
uint16_t h;
static constexpr char text[] = "Hello world ! This is M5Stack scroll test.";
static constexpr size_t textlen = sizeof(text) / sizeof(text[0]);
int textpos = 0;
int scrollstep = 2;

void setup()
{
  display.begin();
  display.setRotation(3);
  display.setBaseColor(TFT_WHITE);
  display.fillScreen(TFT_WHITE);
  display.setFont(&fonts::FreeMonoBoldOblique24pt7b);
  display.setTextColor(TFT_BLACK);
  w = display.width() / 2;
  h = display.height() / 2;
}

void loop()
{
  int32_t cursor_x = display.getCursorX() - scrollstep;
  if (cursor_x <= 0)
  {
    textpos = 0;
    cursor_x = 0;
  }

  display.setCursor(cursor_x, h-24);
  display.scroll(-scrollstep, 0);
  while (textpos < textlen && cursor_x <= display.width())
  {
    display.print(text[textpos++]);
    cursor_x = display.getCursorX();
  }
}

Example Program 3 (Canvas):

cpp 
#include <Arduino.h>
#include <M5GFX.h>

M5GFX display;
M5Canvas canvas(&display);
uint16_t w;
uint16_t h;
static constexpr char text[] = "Hello world ! This is M5Stack scroll test.";
static constexpr size_t textlen = sizeof(text) / sizeof(text[0]);
int textpos = 0;
int scrollstep = 2;

void setup()
{
  display.begin();
  display.setRotation(3);
  display.fillScreen(TFT_WHITE);

  canvas.createSprite(display.width() + 64, 108);
  canvas.fillSprite(TFT_WHITE);
  canvas.setBaseColor(TFT_WHITE);
  canvas.setFont(&fonts::FreeMonoBoldOblique24pt7b);
  canvas.setTextColor(TFT_BLACK);
  canvas.setTextSize(1.5);
}

void loop()
{
  int32_t cursor_x = canvas.getCursorX() - scrollstep;
  if (cursor_x <= 0)
  {
    textpos = 0;
    cursor_x = display.width();
  }

  canvas.setCursor(cursor_x, 0);
  canvas.scroll(-scrollstep, 0);
  while (textpos < textlen && cursor_x <= display.width())
  {
    canvas.setColor(TFT_BLACK);
    canvas.print(text[textpos++]);
    cursor_x = canvas.getCursorX();
  }

  int y = (display.height() - canvas.height()) >> 1;
  canvas.pushSprite(&display, 0, y);
}

Custom Processing

effect

Function Prototype:

void effect(int32_t x, int32_t y, int32_t w, int32_t h, TFunc&& effector) 

Description:

Use a custom transformation function to process the specified rectangular area

Parameters:

x: rectangle start x coordinate
y: rectangle start y coordinate
w: rectangle width
h: rectangle height
effector: transformation function, user-defined

Return:

null

Next 1. Arduino Setup - 1. Arduino IDE Install

1. Arduino Setup

2. Devices & Examples

Tab5

Basic/Gray/M5GO

Fire

Core2/Core2 For AWS

CoreS3

Tough

Atom-Lite / Atom-Matrix

AtomS3 / AtomS3-Lite

Dial

Air Quality

DinMeter

Capsule

Cardputer

Paper

PaperS3

CoreInk

Station Bat/485

StickC

StickC-Plus

StickC-Plus2

StamPLC

TimerCamera

3. M5Unified

M5Unified Setup

M5Unified API

4. M5GFX

M5GFX API

5. Extensions & Examples

Unit

Module

Atomic

Atom DTU

Hat

Sprite Management

Panel Parameters

isEPD

height

width

popState

pushState

setBrightness

getBrightness

setEpdMode

getEpdMode

setResolution

setRotation

getRotation

Color

setBaseColor

getBaseColor

setColor

setRawColor

getRawColor

setColorDepth

getColorDepth

getPalette

getPaletteCount

Clear Screen

clear

clearDisplay

fillScreen

Coordinate Point Setting

setCursor

getCursorX

getCursorY

setPivot

getPivotX

getPivotY

Sprite Area Selection

setAddrWindow

setWindow

setAddrWindow

setWindow

setClipRect

getClipRect

clearClipRect

Sprite Scrolling

scroll