2024/06/03 電子書籍「電子書籍出版・技術文書作成を劇的に加速!秀丸エディタ + Markdown + Pandocの驚異」を出版

M5GFXライブラリの使い方

M5Stack

M5GFXは、M5Stack製品の仕様の異なるディスプレイデバイスを扱うためのグラフィクスライブラリです。LCD,OLED,e-Ink Display等の違いを意識せず共通のAPIで扱うことが可能です。

M5GFXライブラリの概要

M5GFXを使用すると、以下のことができます。

  • ディスプレイの初期化
  • 色の設定
  • 図形の描画
  • 文字列の描画
  • 画像の描画

M5GFXは、以下のAPIで構成されています。

  • M5Canvas:ディスプレイの描画領域を表すクラス
  • M5Color:色を表すクラス
  • M5Draw:図形の描画を行うクラス
  • M5Font:文字列の描画を行うクラス
  • M5Image:画像の描画を行うクラス

M5GFXは、M5Stackの公式ライブラリに含まれています。

M5GFXを使用するには、以下の手順で行います。

  1. M5GFXライブラリをインストールします。
  2. M5Canvasオブジェクトを作成します。
  3. 色を設定します。
  4. 図形や文字列を描画します。

Supported device

M5Stackシリーズの以下の製品をサポートしています。(2023/10/31時点)

  • M5Stack ( Basic / Gray / GO / Fire )
  • M5Stack Core2
  • M5Stack CoreInk
  • M5Stick C
  • M5Stick C Plus
  • M5Stick C Plus2
  • M5Paper
  • M5Tough
  • M5Station
  • M5ATOMS3
  • M5Dial
  • M5DinMeter
  • M5Capsule
  • M5Cardputer
  • UnitOLED
  • UnitMiniOLED
  • UnitLCD
  • UnitRCA / ModuleRCA
  • UnitGLASS
  • UnitGLASS2
  • AtomDisplay / ModuleDisplay

ヘッダファイルのインクリード

下記のデバイスに対応したヘッダファイルをインクルードします。M5StackのコントローラーデバイスはM5GFX.hをインクルードします。

  • M5GFX.h
  • M5UnitLCD.h
  • M5UnitOLED.h
  • M5AtomDisplay.h

詳細は、以下のHPを参照ください。

m5-docs
The reference docs for M5Stack products. Quick start, get the detailed information or instructions such as IDE,UIFLOW,Ar...

M5Canvasについて

M5Canvasは基本的にTFT_eSPIのSpriteと同一です。メモリ上に描くという機能から考えてM5GFXではSpriteではなくCanvasという名称を利用しています。(しかし、TFT-eSPIとの互換性も考慮し、pushSpriteのようなメソッド名は残っています。)

M5Canvasについて

以下のWebページに掲載のサンプルコードです。

m5-docs
The reference docs for M5Stack products. Quick start, get the detailed information or instructions such as IDE,UIFLOW,Ar...

簡単な利用サンプル

#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()
{
}

複数のCanvasを組み合わせた例Canvasを別の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()
{
}

コンストラクタ引数を省略した場合

#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()
{
}

透明色を指定した場合、pushする際にその色は描画されず元々描かれた色が表示されます。重ね合わせた時に透明になるイメージです。

使い方 の2番目のサンプルで透明色に青を指定した場合、青色は透過して背景のピンクになります。

#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()
{
}

拡大縮小と回転

#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;
}

M5GFXの関数一覧

M5GFXの関数一覧です。

詳細は、以下のHPを参照ください。

関数説明
beginパネルを初期化します。
beginTransactionパネルのトランザクションを開始します。
calibrateTouchタッチパネルをキャリブレーションします。
clearパネルをクリアします。引数にカラーコードを指定した場合、その色で初期化します。
clearClipRectsetClipRect() で指定した領域をクリアします。
clearDisplayパネルをクリアします。引数にカラーコードを指定した場合、その色で初期化します。
clearScrollRectsetScrollRect() で指定した領域をクリアします。
color16to24RGB565(16bit)のカラーコードをRGB888(24bit)へ変換します。
color16to8RGB565(16bit)のカラーコードをRGB332(8bit)へ変換します。
color24to16RGB888(24bit)のカラーコードをRGB565(16bit)へ変換します。
color332r, g, bの値からRGB332(8bit)のカラーコードを生成します。
color565r, g, bの値からRGB565(16bit)のカラーコードを生成します。
color888r, g, bの値からRGB888(24bit)のカラーコードを生成します。
color8to16RGB332(8bit)のカラーコードをRGB565(16bit)へ変換します。
convertRawXYgetTouchRaw() で取得した情報を変換します。
copyRect矩形範囲をコピーします。
createPngスクリーンショット機能です。パネルに表示しているデータをPNG形式でメモリに保存します。
createPngスクリーンショット機能です。パネルに表示しているデータをPNG形式でメモリに保存します。
display描画データをパネルへ表示します。(M5Paper, CoreInk, OLEDUnit用の関数です。)
displayBusyパネルがBusyかどうかをチェックします。
dmaBusyパネルのDMAがBusyかチェックします。
drawArc円弧を描きます。r0とr1を指定し厚みのある円弧を描きます。
drawBezierベジェ曲線を描きます。制御点は3点または4点を指定します。
drawBmpBMP形式のビットマップデータを描きます。ファイルやStreamを指定できます。
drawBmpFilebmpファイルのビットマップデータを描きます。
drawBmpUrlURLで指定したBMPデータを描きます。
drawCenterString(drawCentreString)テキストを中寄せで描画します。
drawCharユニコードで文字を描画します。
drawCircle円を描きます。
drawEllipse楕円を描きます。
drawEllipseArc楕円の円弧を描きます。
drawFastHLine水平方向の線を描きます。
drawFastVLine垂直方向の線を描きます。
drawFloatFloat型(浮動少数型)の値を描画します。
drawGradientHLine色が変化する水平方向の線を描きます。
drawGradientLine色が変化する線を描きます。
drawGradientVLine色が変化する垂直方向の線を描きます。
drawJpgJPGデータを描画します。File, Stream等のデータを指定可能です。
drawJpgFileJPGファイルを描画します。
drawJpgUrlURLで指定したJPGデータを表示します。
drawLine線を描く。
drawNumberlong型(整数型)の数値を描画します。
drawPixel点を描画します。
drawPngPNGデータを描画します。FileやStreamを指定することができます。
drawPngFilePNGファイルを描きます。
drawPngUrl指定したURLのPNGデータを描きます。
drawQoiQoiデータを描画します。FileやStreamを指定することができます。
drawQoiFileQoiファイルを描画します。
drawQoiUrl指定したURLのQoiデータを描画します。
drawRect矩形を描きます。
drawRightString右寄せで文字列を描画します。
drawRoundRect角が丸い矩形を描画します。
drawString文字を描画します。
drawTriangle3つの点を指定して三角形を描画します。
effectユーザ定義の関数を用いて矩形範囲を変換します。
endTransactionstartTransaction() とペアで使用します。
endWritestartWrite() とペアで使用します。
fillAffineアフィン変換行列で描画した領域を塗りつぶします。
fillArc塗りつぶした円弧を描きます。
fillCircle塗りつぶした円を描きます。
fillEllipse塗りつぶした楕円を描きます。
fillEllipseArc塗りつぶした円弧を描きます。
fillRect塗りつぶした矩形を描きます。
fillRectAlpha不透明な矩形を描画します。
fillRoundRect角が丸い塗りつぶした矩形を描きます。
fillScreen画面を塗りつぶします。
fillTriangle3つの点を指定して塗りつぶした三角形を描きます。
floodFill指定した座標の色域を近似的に塗りつぶします。
fontHeightReturns the height of the specified font.
fontWidthReturns the width of the specified font.
getAttributeattributeの値を取得します。
getBaseColorsetBaseColor() で設定されたパネルの背景色を取得します。
getBoardボードを取得します。
getBrightnesssetBrightness() で設定した値を取得します。
getClipRectsetClipRectRect() で設定したx,y,w,hを取得します。
getColorDepthsetColorDepth() で設定されたColorDepthを取得します。
getCursorX現在のカーソルX座標を取得します。
getCursorY現在のカーソルY座標を取得します。
getEpdModesetEpdMode() で設定されているE-Paperのモードを取得します。(M5Paperのみ)
getFontsetFont() で設定されているフォントを取得します。
getInstanceM5GFXのインスタンスを取得します。
getInvertinvertDisplay() で設定した値を取得します。
getPaletteパレット情報を取得します。
getPaletteCountパレットの数を取得します。
getPanelパネルを取得します。
getPivotXsetPivot() で設定されたPivotのX座標を取得します。
getPivotYsetPivot() で設定されたPivotのY座標を取得します。
getRawColorsetRawColor() で設定された色を取得します。**注意:**返却値はRGB888形式です。
getRotationsetRotation() で設定されたローテーションの値を取得します。
getScrollRectsetScrollRect() で設定されたx,y,w,hを取得します。
getStartCount実行した startWrite() の回数を取得します。
getSwapBytessetSwapBytes() で設定された値を取得します。
getTextDatumsetTextDatum() で設定された構造体を取得します。
getTextPaddingテキストの余白を取得します。
getTextSizeXsetTextSize() 設定されたテキストサイズの幅を取得します。
getTextSizeYsetTextSize() で設定されたテキストサイズの高さを取得します。
getTextStylesetTextStyle() で設定されたテキスト情報を取得します。
getTouchタッチパネルの情報を取得します。
getTouchRawタッチパネルの情報を取得します。
hasPaletteパレットが設定されているかどうかを返却します。
heightパネルの高さを取得します。
initパネルを初期化します。
initDMADMAを初期化します。
invertDisplay画面の明暗及び色調を反転させて出力するかどうかを設定します。(ネガポジ反転)
isBusSharedバスが共有されているかどうかを取得します。
isEPDe-Paper displayかどうかを取得します。
isReadableパネルの情報を読み込みできるかどうかを取得します。
isSPISharedSPIバスが共有されているかどうかを取得します。
loadFontフォントデータを読み込みます。
paintfloodFill() と同じ機能です。
panelパネルを取得します。
popStateテキスト情報を一時的に待避します。待避した情報は pushState() で戻します。
powerSaveパワーセーブの状態を設定します。
powerSaveOffパワーセーブの状態をOFFにします。
powerSaveOnパワーセーブの状態をONにします。
printカーソル位置に文字列を出力します。ArduinoのPrint.hに準拠しています。
printfカーソル位置に文字列を出力します。ArduinoのLibPrint.hに準拠しています。
printlnカーソル位置に文字列を出力します。文字列の最後に改行コードを追加します。ArduinoのPrint.hに準拠しています。
progressBarプログレスバーを表示します。色は0x09F1(暗い青)のみです。
pushBlocksetWindow() , setAddrWindow() で設定された領域に、行方向に指定された色を描画していきます。
pushImage画像データをPushします。
pushImageAffineアフィン変換して画像を描画します。
pushImageAffineWithAAアンチエイリアスとアフィン変換を行いつつ画像をpushします。
pushPixelssetWindow() , setAddrWindos() で設定された領域に画像データをpushします。
pushPixelsDMADMAに画像データをpushします。
pushStatepopState() で一時待避したテキスト情報をリストアします
qrcode文字列をqrcodeに変換します。
readData1616bitのデータをパネルから読み込みます。
readData3232bitのデータをパネルから読み込みます。
readData88bitのデータをパネルから読み込みます。
readPixel指定した座標のカラーコード(RGB565)を読み取ります。
readPixelRGB指定した座標のカラーコード(RGB888)を読み取ります。
readRect指定された矩形領域のデータを読み込みます。(RGB565)
readRectRGB指定された矩形領域のデータを読み込みます。(RGB888)
scrollパネルに表示されているデータをスクロールします。
setAddrWindowwritePixels() , pushPixels() , pushBlock() の描画先となる範囲を指定します。
setAutoDisplayM5Paper, CoreInk, UnitOLEDのみの機能です。 trueを設定すると、 display() を実行しなくても書き込みを行うと即描画されます。
setBaseColorパネルの背景色を設定します。スクロール機能で描画される描画領域外の色を設定することができます。 getBaseColor() と対の関数です。
setBrightnessディスプレイパネルの明るさを設定します。
setClipRect描画に使用する矩形領域を指定します。
setColor描画色を指定します。
setColorDepthColorDepthを設定します。
setCursorカーソル位置を指定します。
setEpdModeE-Paperのモードを指定します。(M5Paperのみ)
setFontデフォルトフォントを指定します。
setPivotPivot座標を設定します。
setRawColor色を指定します。
setResolutionM5AtomDisplayのみの機能です。 解像度の設定を行います。
setRotationパネルの回転方向を指定します。
setScrollRect指定した矩形領域でテキストが溢れた場合、スクロールするようになります。
setSwapBytesパネルへデータを書き込む際にスワップするかどうかを設定します。
setTextColorSet TextColor.
setTextDatumテキストを表示するときのデフォルト基準点(datum)を設定します。
TL_DATUM = Top left
TC_DATUM = Top centre
TR_DATUM = Top right
ML_DATUM = Middle left
MC_DATUM = Middle centre
MR_DATUM = Middle right
BL_DATUM = Bottom left
BC_DATUM = Bottom centre
BR_DATUM = Bottom right
setTextScrollテキストスクロールを有効にします。
setTextSizeテキストサイズを指定します。実数で指定が可能です。
setTextStyleテキストの書式を設定します。
setTextWrapX軸は文字列の折返しをするかどうか、Y軸は画面下部まで表示したあと上に戻るかどうかを指定します。
setTouchCalibratecalibrateTouch() で取得したタッチパネルのキャリブレーション値を設定します。
setWindowwritePixels() , pushPixels() , pushBlock() 等の描画先となる範囲を指定します。
showFontDisplay the specified time font.
sleepパネルをスリープします。 起動は wakeup() を使います。
startWriteSPIバスのCSをアサートします。 endWrite() と対で使用します。startWrite()をパネル描画の際に明示的に記述することによりDMAバッファを効率的に使用することが可能になります。
swap565M5Canvas上の描画データは、カラーコードがスワップしています。そのためgetBuffer()で取得したデータを扱う場合にswap565を利用します。
swap888M5Canvas上の描画データは、カラーコードがスワップしています。そのためgetBuffer()で取得したデータを扱う場合にswap888を利用します。
textLength指定した幅に、指定した文字列のうち表示可能な文字数を取得します。
textWidthパネルに文字列を表示したときの表示幅(pixel)を取得します。フォントを省略するとデフォルトフォントで計算します。
touchタッチデバイスが有効な場合、ITouchポインタを返します。
unloadFontsetFont() で設定されたフォントを、アンロードして初期値に戻します。(&fonts::Font0)
waitDisplayパネルの描画が終わるまで待機します。
waitDMADMAが使用中の場合待機します。
wakeupsleep() でスリープした状態のパネルを起動します。
widthパネルの幅を返します。
writeColorsetWindow() で設定した矩形領域に指定した色を行方向に指定された長さ描画していきます。
writeCommand16パネルに16bitのコマンドを書き込みます。
writeData16パネルに16bitデータを書き込みます。
writeData32パネルに32bitデータを書き込みます。
writeDataパネルに8bitデータを書き込みます。
writeFastHLine水平方向の線を描きます。
writeFastVLine垂直方向の線を描きます。
writeFillRect矩形を描きます。
writeIndexedPixelsカラーパレット情報を利用して画像データを描画します。
writePixel指定座標に点を描画します。
writePixelssetWindow() , setAddrWindos() で設定された領域に画像データをpushします。
writePixelsDMAsetWindow() , setAddrWindos() で設定した矩形領域に画像データを指定された長さだけDMA転送します。矩形領域の左上から描画が始まります。

LGFX_Buttonについて

Adafruit GFX Library のAdafruit_GFX_Buttonとの互換性を取るためのクラスです。 画面上に仮想的なボタンを配置して簡単に制御できるようになります。

関数一覧

関数説明
contains指定した座標がボタンの位置に含まれるかどうかを判定します。タッチパネルでボタンが押されたかどうかの判断に利用します。
drawButtonボタンを描画します。引数のinvertedをtrueにすると背景色が反転します。
initButtonボタンを初期状態を設定します。
isPressedpress() で設定したボタンの状態を返却します。
justPressedボタンが押されたかどうか判定します。
justReleasedボタンを離したかどうか判定します。
pressボタンの状態を設定します。
setLabelDatumラベルの 基準点(datum) を設定します。
m5-docs
The reference docs for M5Stack products. Quick start, get the detailed information or instructions such as IDE,UIFLOW,Ar...

Appendex

以下の説明が、以下のHPにあります。

  • カラーコードについて
  • 定義済みの色
  • テキストの基準点(datum)について
  • 画像の基準点(datum)について
  • フォント一覧
  • ユニコードフォント
  • ColorDepthについて
  • enum epd_mode_t
  • struct TextStyle
  • struct FontMetrics
  • startWrite()とendWrite()
  • draw/push系とwrite系の関数の違いについて
m5-docs
The reference docs for M5Stack products. Quick start, get the detailed information or instructions such as IDE,UIFLOW,Ar...

参考URL

以下のURLも参考にしてください。

タイトルとURLをコピーしました