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
  • setClipRect
  • getClipRect
  • clearClipRect
• Sprite Scrolling
  • scroll
  • setTextScroll
  • setScrollRect
  • getScrollRect
  • clearScrollRect
• 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

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

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

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)

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

Parameters:

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

Return:

• null

setWindow

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

Parameters:

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

Return:

• null

setWindow

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:

#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

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:

#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):

#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):

#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