About M5Canvas

M5Canvas is basically used in the same way as TFT_eSPI's Sprite. We call it M5Canvas because it is appropriate to call it "Canvas" in the sense of drawing on memory, not "Sprite" as defined within M5GFX.(However, methods such as pushSprite remain for compatibility with TFT_eSprite.)

This document will show you how to use it briefly. For detailed API information, refer to here .

Benefits of Canvas

• It can be drawn in memory in advance and displayed on the panel at once for quick display.

• Useful for displaying small characters, etc.

• Transparent colors can be used to provide overlap.

• When drawing on the display, scaling, rotation, and anti-aliasing can be performed.

Constructor

Syntax:

• No arguments
  Note that if the argument is not specified, it must be specified at push or drawing time, or problems will occur.

M5Canvas()

• Specify M5GFX.
  If M5GFX is specified as an argument, it will draw to the M5GFX device by default.

M5Canvas(M5GFX&)

• Specify M5Canvas.
  If M5Canvas is specified as an argument, it will draw to the M5Canvas by default.

M5Canvas(M5Canvas&)

How to use

• 1.Simple Use

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

M5GFX display;
M5Canvas canvas(&display);

int32_t x;
int32_t y;

void setup()
{
  display.begin();
  display.fillScreen(TFT_BLACK);
  
  x = display.width() / 2;
  y = display.height() / 2;
  canvas.createSprite(50, 50);
  canvas.fillSprite(TFT_PINK);
  canvas.fillRect(10, 10, 20, 20, TFT_RED);
  canvas.println("M5Canvas");

  // Only the following process is actually drawn on the panel.
  display.startWrite(); 
  display.println("Display");
  canvas.pushSprite(x, y);
  display.endWrite();
}


void loop()
{
}

• 2.Combine multiple Canvas to draw.
  It is also possible to draw a canvas to another canvas.

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

M5GFX display;
M5Canvas canvas(&display);
M5Canvas sub_canvas1(&canvas);
M5Canvas sub_canvas2(&canvas);

int32_t x;
int32_t y;

void setup()
{
  display.begin();
  display.fillScreen(TFT_BLACK);
  
  x = display.width() / 2;
  y = display.height() / 2;
  canvas.createSprite(80, 80);
  canvas.fillSprite(TFT_PINK);
  canvas.fillRect(10, 10, 10, 10, TFT_RED);
  canvas.println("M5Canvas");

  sub_canvas1.createSprite(30, 30);
  sub_canvas1.fillSprite(TFT_BLUE);
  sub_canvas1.println("sub1");
  sub_canvas1.fillCircle(15, 15, 5, TFT_YELLOW);
  sub_canvas2.createSprite(30, 30);
  sub_canvas2.fillSprite(TFT_GREEN);
  sub_canvas2.println("sub2");
  sub_canvas2.fillTriangle(15, 10, 0, 30, 30, 30, TFT_BLUE);

  sub_canvas1.pushSprite(5, 30);
  sub_canvas2.pushSprite(40, 30);  

  // Only the following process is actually drawn on the panel.
  display.startWrite();
  display.println("Display");
  canvas.pushSprite(x, y);
  display.endWrite();
}


void loop()
{
}

• 3.If arguments are omitted.

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

M5GFX display;
M5Canvas canvas;

int32_t x;
int32_t y;

void setup()
{
  display.begin();
  display.fillScreen(TFT_BLACK);
  
  x = display.width() / 2;
  y = display.height() / 2;
  canvas.createSprite(50, 50);
  canvas.fillSprite(TFT_PINK);
  canvas.fillRect(10, 10, 20, 20, TFT_RED);
  canvas.println("M5Canvas");

  // Only the following process is actually drawn on the panel.
  display.startWrite();
  display.println("Display");
  canvas.pushSprite(&display, x, y);
  display.endWrite();
}

void loop()
{
}

Transparent color

If a transparent color is specified, that color can be made transparent.

If you specify blue as the transparency color in the second Example in How to Use , the blue area becomes transparent and the background becomes pink.

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

M5GFX display;
M5Canvas canvas(&display);
M5Canvas sub_canvas1(&canvas);
M5Canvas sub_canvas2(&canvas);

int32_t x;
int32_t y;

void setup()
{
  display.begin();
  display.fillScreen(TFT_BLACK);
  
  x = display.width() / 2;
  y = display.height() / 2;
  canvas.createSprite(80, 80);
  canvas.fillSprite(TFT_PINK);
  canvas.fillRect(10, 10, 10, 10, TFT_RED);
  canvas.println("M5Canvas");

  // Draw on a small canvas 1.
  sub_canvas1.createSprite(30, 30);
  sub_canvas1.fillSprite(TFT_BLUE);
  sub_canvas1.println("sub1");
  sub_canvas1.fillCircle(15, 15, 5, TFT_YELLOW);

  // Draw on a small canvas 2.
  sub_canvas2.createSprite(30, 30);
  sub_canvas2.fillSprite(TFT_GREEN);
  sub_canvas2.println("sub2");
  sub_canvas2.fillTriangle(15, 10, 0, 30, 30, 30, TFT_BLUE);

  // Draw two smaller canvases on the canvas.
  sub_canvas1.pushSprite(5, 30, TFT_BLUE);
  sub_canvas2.pushSprite(40, 30, TFT_BLUE);  

  // Only the following process is actually drawn on the panel.
  display.startWrite();
  display.println("Display");
  canvas.pushSprite(x, y);
  display.endWrite();
}


void loop()
{
}

RotateZoom

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

static M5GFX display;
static M5Canvas canvas1(&display);
static M5Canvas canvas2(&canvas1);
static int32_t width = 100;
static size_t count = 0;

void setup(void)
{
  display.init();
  display.fillScreen(TFT_RED);
  width = std::min(width, (std::max(display.width(), display.height())+10)) | 1;
  canvas1.setColorDepth(8);
  canvas1.createSprite(width + 30, width + 30);
  canvas1.fillSprite(TFT_RED);
  canvas2.setColorDepth(8);
  canvas2.createSprite(width, width);
  canvas2.fillSprite(TFT_RED);
  canvas2.fillRect(0, width>>1, width>>1, width>>1, TFT_BLUE);

}

float scale = 0.0f;

void loop(void)
{
  ++count;
  canvas1.fillSprite(TFT_RED);
  scale += 0.01f;
  canvas2.pushRotateZoom(0, scale, scale);

  // Only the following process is actually drawn on the panel.
  canvas1.pushRotateZoom(count * 0.5f, 1.0, 1.0);
  if (scale > 1.0f) scale = 0.0f;
}

Advanced Examples

M5GFX + OLEDUnit

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

static M5GFX display;
static M5UnitOLED oled;

static M5Canvas canvas1(&display);
static M5Canvas canvas2(&canvas1);
static int32_t width = 100;
static size_t count = 0;

void setup(void)
{
  display.init();
  oled.init();
  display.fillScreen(TFT_RED);
  width = std::min(width, (std::max(display.width(), display.height())+10)) | 1;
  canvas1.setColorDepth(8);
  canvas1.createSprite(width + 30, width + 30);
  canvas1.fillSprite(TFT_RED);
  canvas2.setColorDepth(8);
  canvas2.createSprite(width, width);
  canvas2.fillSprite(TFT_RED);
  canvas2.fillRect(0, width>>1, width>>1, width>>1, TFT_BLUE);
}

float scale = 0.0f;

void loop(void)
{
  ++count;
  canvas1.fillSprite(TFT_RED);
  scale += 0.01f;
  canvas2.pushRotateZoom(0, scale, scale);
  canvas1.pushRotateZoom(count * 0.5f, 1.0, 1.0);
  canvas1.pushRotateZoom(&oled, count * 0.5f, 1.0, 1.0);
  if (scale > 1.0f) scale = 0.0f;
}