Features - pixelmatix/SmartMatrix GitHub Wiki

Overview

SmartMatrix Library is designed to refresh LEDs with high quality graphics, using simple Arduino sketches. There's a lot that SmartMatrix Library sets up to do in the background when you call matrix.begin(), but for the most part you don't have to worry about it. Many times a second, SmartMatrix Library is telling each Layer in your sketch to update, collecting the updated pixels from each Layer and applying optional color correction, assembling them into a single image to send out to the LEDs, then setting up the hardware to shift the image out to the LEDs using DMA.

Layers

SmartMatrix Library has three main types of Layers built in.

• backgroundLayer
  • This is a non-transparent Layer that holds pixels with high color depth (24 or 48 bpp) and pixels can be set through drawing functions (e.g. backgroundLayer.drawPixel() or backgroundLayer.fillCircle()) or by directly accessing the pixel buffer and setting the pixels directly. The Layer is double buffered, so one buffer holds the content that is being refreshed to the screen, and another buffer is used for drawing. When you're done drawing to the buffer and want the contents refreshed to the screen, call backgroundLayer.swapBuffers().
• scrollingLayer
  • This layer is transparent, so wherever there are blank pixels in this Layer, you can see through to the Layer(s) behind. This Layer holds text to be scrolled across the screen. Set the parameters of the scrolling text (e.g. scrollingLayer.setFont() and scrollingLayer.setColor()) and then when you call scrollingLayer.start("Scroll This Text") with the text you want displayed, the Layer takes care of updating the scrolling text automatically.
• indexedLayer
  • This Layer is used for drawing similar to backgroundLayer, but all pixels are the same color (to save memory), and any pixel that isn't set is transparent so you can see through to the Layer(s) behind.

You can add multiple Layers, to your sketch, the only limit is available memory and CPU, as each Layer requires memory to hold the pixels, and CPU to assemble the pixels for each screen refresh.

You can customize or make your own Layers added to your sketch folder if you want. See the Continuum sketch on GitHub for an example that uses a custom Layer.

The new Adafruit_GFX Layers can be used in the same way as the main Layers, but have some important differences, see the section below.

API

Until more documentation is written, the Examples in the library are a good way to see how the API is used.

Init

See the README hosted in the SmartMatrix GitHub Repo for installation instructions

The file describing the hardware you're using needs to be included at the top of the sketch, before #include <SmartMatrix.h>. The example sketches include the most common hardware description headers.

// uncomment one line to select your MatrixHardware configuration - configuration header needs to be included before <SmartMatrix.h>
//#include <MatrixHardware_Teensy3_ShieldV4.h>        // SmartLED Shield for Teensy 3 (V4)
//#include <MatrixHardware_Teensy4_ShieldV5.h>        // SmartLED Shield for Teensy 4 (V5)
//#include <MatrixHardware_Teensy3_ShieldV1toV3.h>    // SmartMatrix Shield for Teensy 3 V1-V3
//#include <MatrixHardware_Teensy4_ShieldV4Adapter.h> // Teensy 4 Adapter attached to SmartLED Shield for Teensy 3 (V4)
//#include <MatrixHardware_ESP32_V0.h>                // This file contains multiple ESP32 hardware configurations, edit the file to define GPIOPINOUT (or add #define GPIOPINOUT with a hardcoded number before this #include)
//#include "MatrixHardware_Custom.h"                  // Copy an existing MatrixHardware file to your Sketch directory, rename, customize, and you can include it like this

More details on the MatrixHardware Header files will be documented here

Next, include SmartMatrix Library:

#include <SmartMatrix.h>

This section describes the settings used for SmartMatrix Library:

#define COLOR_DEPTH 24                  // Choose the color depth used for storing pixels in the layers: 24 or 48 (24 is good for most sketches - If the sketch uses type `rgb24` directly, COLOR_DEPTH must be 24)
const uint16_t kMatrixWidth = 32;       // Set to the width of your display, must be a multiple of 8
const uint16_t kMatrixHeight = 32;      // Set to the height of your display
const uint8_t kRefreshDepth = 36;       // Tradeoff of color quality vs refresh rate, max brightness, and RAM usage.  36 is typically good, drop down to 24 if you need to.  On Teensy, multiples of 3, up to 48: 3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42, 45, 48.  On ESP32: 24, 36, 48
const uint8_t kDmaBufferRows = 4;       // known working: 2-4, use 2 to save RAM, more to keep from dropping frames and automatically lowering refresh rate.  (This isn't used on ESP32, leave as default)
const uint8_t kPanelType = SM_PANELTYPE_HUB75_32ROW_MOD16SCAN;   // Choose the configuration that matches your panels.  See more details in MatrixCommonHub75.h and the docs: https://github.com/pixelmatix/SmartMatrix/wiki
const uint32_t kMatrixOptions = (SM_HUB75_OPTIONS_NONE);        // see docs for options: https://github.com/pixelmatix/SmartMatrix/wiki

• COLOR_DEPTH
  • Choose the color depth used for storing pixels in the layers: 24 or 48
  • 24 is good for most sketches
  • If the sketch uses type rgb24 directly, COLOR_DEPTH must be 24
• kMatrixWidth
  • Set to the width of your display, must be a multiple of 8
• kMatrixHeight
  • Set to the height of your display
• kRefreshDepth
  • Tradeoff of color quality vs refresh rate, max brightness, and RAM usage.
  • 36 is typically good, drop down to 24 if you need to.
  • On Teensy you can use any multiple of 3, up to 48: 3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42, 45, 48.
  • On ESP32, you're limited to these values: 24, 36, 48
• kDmaBufferRows
  • Known working values: 2-4
  • Use 2 to save RAM, and increase to keep from dropping frames and automatically lowering refresh rate
  • (This isn't used on ESP32, leave as default)
• kPanelType
  • For the most common panels, kPanelType is one of the three values below, chosen easily from your panel's height (number of rows):
    • SM_PANELTYPE_HUB75_32ROW_MOD16SCAN
    • SM_PANELTYPE_HUB75_16ROW_MOD8SCAN
    • SM_PANELTYPE_HUB75_64ROW_MOD32SCAN
  • Some panels light up more than two rows at a time, and have more complex mapping. See details in Hub75-Panels and Multi-Row-Panels.
    • SM_PANELTYPE_HUB75_16ROW_32COL_MOD2SCAN
    • SM_PANELTYPE_HUB75_16ROW_32COL_MOD2SCAN_V2
    • SM_PANELTYPE_HUB12_16ROW_32COL_MOD4SCAN
    • SM_PANELTYPE_HUB75_16ROW_32COL_MOD4SCAN
    • SM_PANELTYPE_HUB75_16ROW_32COL_MOD4SCAN_V2
    • SM_PANELTYPE_HUB75_16ROW_32COL_MOD4SCAN_V3
    • SM_PANELTYPE_HUB75_16ROW_32COL_MOD4SCAN_V4
    • SM_PANELTYPE_HUB75_32ROW_64COL_MOD8SCAN
    • SM_PANELTYPE_HUB75_64ROW_64COL_MOD16SCAN
  • These values are used just for reverse engineering your Multi Row Panel using the MultiRowRefreshMapping example sketch
    • SM_PANELTYPE_HUB75_4ROW_MOD2SCAN
    • SM_PANELTYPE_HUB75_8ROW_MOD4SCAN
    • SM_PANELTYPE_HUB75_2ROW_MOD1SCAN
    • SM_PANELTYPE_HUB75_4ROW_MOD2SCAN_ALT_ADDX
    • SM_PANELTYPE_HUB75_8ROW_MOD4SCAN_ALT_ADDX
  • Note for backwards compatibility with SmartMatrix Library 3.x, you can use SMARTMATRIX_HUB75 instead of SM_PANELTYPE_HUB75, e.g. SMARTMATRIX_HUB75_32ROW_MOD16SCAN
• kMatrixOptions
  • See more details below

Depending on what layers you're using, you'll want to describe the layer options next. The default option of "NONE" is usually correct:

const uint8_t kBackgroundLayerOptions = (SM_BACKGROUND_OPTIONS_NONE);
const uint8_t kScrollingLayerOptions = (SM_SCROLLING_OPTIONS_NONE);
const uint8_t kIndexedLayerOptions = (SM_INDEXED_OPTIONS_NONE);

Next allocate the memory and classes for the matrix and the layers. You'll always need SMARTMATRIX_ALLOCATE_BUFFERS, but may need only some of the Layer allocations:

SMARTMATRIX_ALLOCATE_BUFFERS(matrix, kMatrixWidth, kMatrixHeight, kRefreshDepth, kDmaBufferRows, kPanelType, kMatrixOptions);

SMARTMATRIX_ALLOCATE_BACKGROUND_LAYER(backgroundLayer, kMatrixWidth, kMatrixHeight, COLOR_DEPTH, kBackgroundLayerOptions);

SMARTMATRIX_ALLOCATE_SCROLLING_LAYER(scrollingLayer, kMatrixWidth, kMatrixHeight, COLOR_DEPTH, kScrollingLayerOptions);

SMARTMATRIX_ALLOCATE_INDEXED_LAYER(indexedLayer, kMatrixWidth, kMatrixHeight, COLOR_DEPTH, kIndexedLayerOptions);

Then, add the layers (from background to foreground) and initialize the library inside setup():

void setup() {
  matrix.addLayer(&backgroundLayer); 
  matrix.addLayer(&scrollingLayer); 
  matrix.addLayer(&indexedLayer); 
  matrix.begin();
}

The above minimal sketch will start refreshing the matrix with the content of the Layers, but there's no content in the Layers so the display will be blank.

Colors

The library mostly uses 24-bit color for working with graphics. Color data is stored in a rgb24 object, with 8-bits for each color:

typedef struct rgb24 {
  uint8_t red;
  uint8_t green;
  uint8_t blue;
} rgb24;

rgb48 can also be used if your sketch needs it, but most times you only need rgb24.

rgb24 myColor = {0xff, 0xff, 0xff}; // white

Or set primary colors directly:

rgb24 myColor;
myColor.red = 0xff;
myColor.green = 0;
myColor.blue = 0;

All drawing functions take an rgb24 color as an argument. You can reference a color you set previously, or define the color as part of the function call.

rgb24 myColor = {0xff, 0xff, 0xff}; // white
drawPixel(0,0,myColor);

drawPixel(0,0, {0xff, 0, 0});

Matrix Configuration

There are several options that can be configured in the library.

Rotation
To rotate the display in a multiple of 90 degrees, use setRotation(rotationDegrees rotation);

matrix.setRotation(rotation180);

It's best to do this early before drawing anything to the display. Data drawn to the buffer is not rotated, so if you need to rotate in the middle of your program, do this:

backgroundLayer.fillScreen({0,0,0}); // clear screen by filling with black
backgroundLayer.swapBuffers();
matrix.setRotation(rotation90); // rotate to 90 degree position
// now draw your screen again

After rotating the screen, the width and height of the buffer may change. You can get quick access to the current width and height with these functions:

uint16_t getScreenWidth(void);
uint16_t getScreenHeight(void);

For example draw a white border around the screen (this example works with all rotations - even on non-square 16x32 display)

backgroundLayer.drawRectangle(0,0, matrix.getScreenHeight()-1, backgroundLayer.getScreenWidth()-1, {0xff, 0xff, 0xff});

LED displays can be very bright, and sometimes you want to dim the display. The SmartMatrix Library makes this easy without losing color-depth while dimming

void setBrightness(uint8_t brightness);

matrix.setBrightness(255); // max brightness
matrix.setBrightness(25); // 10% brightness, for a dark room

There are more options, see the FeatureDemo example sketch for example code showing how to use all of the options

Layers Overview

All the graphics displayed on the matrix are stored inside Layers. Each time SmartMatrix Library updates the screen with new content, it pulls data from each layer, starting with the background Layer (the Layer that was first added with matrix.addLayer()), and finishing with the foreground Layer (the last matrix.addLayer() call). The opaque pixels in each Layer are drawn on top of the previous Layers, with any transparent pixels left alone, so you can see through multiple layers (see FeatureDemo and MultipleTextLayers* sketches for a good examples of this).

There are three main types of Layers included in SmartMatrix Library, but a custom Layer type can be created and added to your sketch if you need.

Background Layer

The background layer is an opaque (no transparency) Layer with storage for a unique color for each pixel in the Layer. Drawing functions update a virtual screen that is not used for refreshing the display until the swapBuffers() method is called. The swapBuffers() method waits until the next full screen refresh, then swaps the drawing buffer with the refresh buffer to display on the new graphics on the screen.

backgroundLayer.swapBuffers();

By default, swapBuffers() makes a copy of the drawing buffer so you can continue adding to your drawing. If you don't care what's in the drawing buffer because you fill it completely each frame, you can call backgroundLayer.swapBuffers(false), which disables the copy and returns faster.

backgroundLayer.fillScreen({0xff,0,0});
backgroundLayer.swapBuffers(false);
delay(1000);
backgroundLayer.fillScreen({0,0xff,0});
backgroundLayer.swapBuffers(false);

The SmartMatrix drawing functions are very similar to the functions used by the Adafruit Graphics Library, with a few differences explained below. Adafruit has an excellent reference on library functions that mostly applies to the SmartMatrix Library:
Adafruit Graphics Library - Adafruit Learning System

SmartMatrix Library differences from Adafruit Graphics Library:

• Color is set using type rgb24 not uint16_t
• Additional functions are available for filled shapes with an outline around the shape
• SmartMatrix Library uses its own set of fonts, and doesn't support scaling
• Scaling the fonts is not available as it is better to use a large size font directly
• Not implemented: Advanced character drawing functions using print()

Note that as of SmartMatrix Library 4.0, there are fully Adafruit_GFX compatible Layers, described in a section below.

See the FeatureDemo example sketch for example code showing how to use all of the Background Layer features

Advanced Background Layer Use

The FastLED_Functions example shows how to get a pointer to the raw bitmaps inside the Background Layer and set the memory directly for more efficient drawing.

Drawing Raw Bitmaps

Here's how to add a bitmap to your sketch and display it.

Start by finding a bitmap file that you want to import. An icon sized appropriately for your display is a good place to start, or search Google Images limiting the search to a file with dimension that you want:
Google Image Search for 32x32 "Icon"

Download GIMP (GNU Image Manipulation Program), which is a free cross-platform image editing tool.

Open the image in GIMP, make any edits that you want, then under the File menu choose export, and select file type "C Source Code".

Type in a name with .c extension, and click Export. In the options dialog, first give your bitmap a unique name for "Prefixed Name", this is how you will refer to the image in Arduino. For this example we'll use "testbitmap". Uncheck the rest of the options, and make sure Opacity is left at 100. Click Export.

Copy the .c file to your Arduino project directory. Include the .c file you created at the top of your project, e.g. #include "testbitmap.c"

The Bitmaps example included with the SmartMatrix Library gives example code and more details on how to get the bitmap from the C file to the screen.

Scrolling Layer

It's popular to use LED matrix displays for a scrolling text marquee, and the SmartMatrix Library makes this easy to do. Just configure how you want the text to be displayed, then call scrollText() with the text to display and the number of times you want it to scroll across the screen. The text scrolls on top of the main drawing buffer without modifying it, so you can continue drawing to the screen behind the text.

    scrollingLayer.setScrollMode(wrapForward);
    scrollingLayer.setScrollSpeed(10);
    scrollingLayer.setScrollFont(font3x5);
    scrollingLayer.setScrollColor({0xff,0xff,0xff});
    scrollingLayer.scrollText("Wrap message 4 times", 4);

    scrollingLayer.setScrollMode(bounceForward);
    scrollingLayer.setScrollSpeed(20);
    scrollingLayer.setFont(font5x7);
    scrollingLayer.setScrollColor({0x00,0xff,0x00});
    scrollingLayer.scrollText("Bounce Forever", -1);

Check the status of your scrolling text by using getScrollStatus(), which returns a positive number indicating the number of loops left if running, -1 indicating the scrolling will run forever, or zero indicating scrolling is complete.

    scrollingLayer.scrollText("Display this message twice", 2);
    
    // wait for scrolling to finish
    while(scrollingLayer.scrollText());
    
    scrollingLayer.scrollText("Then display this message once", 1);

You can stop the scrolling text at any time by using stopScrollText().

    scrollingLayer.scrollText("Scroll this text forever", -1);

    delay(1000);
    scrollingLayer.stopScrollText();

See the FeatureDemo example sketch for example code showing how to use all of the Scrolling Layer features

Indexed Layer

Indexed Layer is a transparent Layer where all pixels can be set to either transparent or opaque, with a single opaque color that is applied to all opaque pixels. (The "Indexed" name is a bit misleading, it would more accurately be called something like "Mono Transparent".) Its API is similar to Background Layer, with not as many features added.

This Layer is useful for putting simple graphics - e.g. text for a menu, or a cursor - above Background Layer.

See the FeatureDemo example sketch for example code showing how to use all of the Indexed Layer features

Color Correction

Our eyes don't see color linearly, but LEDs display color linearly. Without color (gamma) correction, colors will look washed out on the panel. Adafruit Learning System has a good tutorial on this issue and a fix. SmartMatrix Library uses this technique but apples the color correction automatically so you don't have to think about it. Additionally, by default SmartMatrix Library takes your 24-bit graphics and refreshes them in 36-bit color on the panel, with color correction applied during the mapping from 24-bit to 36-bit color depth, so there's less loss of color depth (less visible stepping when fading between two colors).

There is an option to enable and disable color (gamma) correction for each Layer:

void enableColorCorrection(bool enabled);

e.g.
rgb24 fullRed = {0xff, 0, 0};
rgb24 halfRed = {0xff/2, 0, 0};
rgb24 quarterRed = {0xff/4, 0, 0};

backgroundLayer.enableColorCorrection(false);
backgroundLayer.drawRectangle(0,0, matrix.getScreenHeight(), matrix.getScreenWidth()/3, fullRed);
backgroundLayer.drawRectangle(matrix.getScreenWidth()/3,0, backgroundLayer.getScreenHeight(), matrix.getScreenWidth()/3, halfRed);
backgroundLayer.drawRectangle(matrix.getScreenWidth()/3*2,0, backgroundLayer.getScreenHeight(), matrix.getScreenWidth()/3, quarterRed);
backgroundLayer.swapBuffers();

The red rectangle on the left is twice as bright as the one in the middle, and four times as bright as the one on the right, but it doesn't look that way to our eyes.

Add this to the code to try it again with color correction enabled:

backgroundLayer.enableColorCorrection(true);

Chaining and Stacking Multiple Panels

You can chain several panels together to create a wider or taller display than one panel would allow. Set kMatrixWidth and kMatrixHeight to the overall width and height of your display. If your display is more than one panel high, set kMatrixOptions to how you tiled your panels:

• Panel Order - By default, the first panel of each row starts on the same side, so you need a long ribbon cable to go from the last panel of the previous row to the first panel of the next row. SM_HUB75_OPTIONS_C_SHAPE_STACKING inverts the panel on each row to minimize the length of the cable going from the last panel of each row the first panel of the other row.
  • Note: SM_HUB75_OPTIONS_C_SHAPE_STACKING isn't compatible with panels that require the Multi Row Refresh Mapping feature (if your kPanelType value includes the column size, it likely requires Multi Row Refresh Mapping, e.g. SM_PANELTYPE_HUB75_16ROW_32COL_MOD2SCAN)
  • Note: the ESP32 Platform doesn't support SM_HUB75_OPTIONS_C_SHAPE_STACKING yet
• Panel Direction - By default the first panel is on the top row. To stack panels the other way, use SM_HUB75_OPTIONS_BOTTOM_TO_TOP_STACKING.
• To set multiple options, use the bitwise-OR operator e.g. for C-shape Bottom-to-top stacking: const uint8_t kMatrixOptions = (SM_HUB75_OPTIONS_C_SHAPE_STACKING | SM_HUB75_OPTIONS_BOTTOM_TO_TOP_STACKING);

Note: the stacking direction was reversed in the teensylc and teensy4 branches prior to the release of SmartMatrix Library 4.0. The stacking direction is still reversed for the ESP32 Platform as of SmartMatrix Library 4.0.3, and will be fixed at some point in the future.

Matrix Initialization Options

SM_HUB75_OPTIONS_NONE - This is the default option with panel layout set to Z-shaped with Top to Bottom stacking.

Set multiple options like this:

const uint32_t kMatrixOptions = (SM_HUB75_OPTIONS_C_SHAPE_STACKING | SM_HUB75_OPTIONS_BOTTOM_TO_TOP_STACKING);

Panel Layout Options

• SM_HUB75_OPTIONS_C_SHAPE_STACKING
  • See notes above
• SM_HUB75_OPTIONS_BOTTOM_TO_TOP_STACKING
  • See notes above

Teensy 4 Specific Options

• SM_HUB75_OPTIONS_T4_CLK_PIN_ALT
  • Swaps to use the alternate pin for the HUB75 Clock signal on the Teensy 4. See more Details in the SmartLED Shield for Teensy 4 assembly instructions and on the page for the T4 to T3 Adapter

ESP32 Specific Options

• SM_HUB75_OPTIONS_MATRIXCALC_LOWPRIORITY
  • This changes the MatrixCalc task to run at low priority, if you need to run another task at a higher priority
• SM_HUB75_OPTIONS_ESP32_CALC_TASK_CORE_1
  • This moves the MatrixCalc Task to Core 1 instead of the default of Core 0
• SM_HUB75_OPTIONS_ESP32_INVERT_CLK
  • This inverts the polarity of the Clock output to the HUB75 panel, which can be useful for some hardware configurations

Panel Type Options

• SM_HUB75_OPTIONS_FM6126A_RESET_AT_START
  • This sends the FM6126A Reset signal at start, use this if your panel has the FM6126A/FM6126B and is blank or doesn't display correctly without this option. See HUB75 Panels for more details
• SM_HUB75_OPTIONS_HUB12_MODE
  • This advanced option enables limited support for HUB12 panels (search SmartMatrix Community for more details)

For backwards compatibility with SmartMatrix Library 3.x, the above options are available with prefix SMARTMATRIX_OPTIONS_ e.g. SMARTMATRIX_OPTIONS_C_SHAPE_STACKING

Adafruit_GFX Layers

New in SmartMatrix Library 4.0 are the "GFX" Layers, which use the Adafruit_GFX library for drawing and fonts. The Layers were written to be mostly backwards compatible with the Background, Indexed, and Scrolling Layers in SmartMatrix 3.x, but there are some key differences.

The GFX Layers are new code that haven't been thoroughly tested or put through their paces by thousands of users, so you may want to wait for a few minor releases after 4.0 to switch if you are looking for reliable code.

You may want to switch to the new layers for the more robust Adafruit_GFX library API including support for larger and custom fonts, plus the new Mono Layer is more CPU efficient than the existing Indexed and Scrolling Layers.

You may not want to switch as the new Mono Layer is less RAM efficient when using large strings and fonts for scrolling, and there's more work involved in deciding how much RAM to allocate to the Layer.

There is now a new SMLayerBackgroundGFX layer (equivalent to SMLayerBackground) and new SMLayerGFXMono layer (equivalent to SMLayerIndexed and SMLayerScrolling combined). Both layers inherit from Adafruit_GFX, so you can use any of the Adafruit_GFX library functions with the new layers.

Adafruit_GFX uses uint16_t (equivalent to rgb16 or rgb565) to store colors, which is a downgrade if you’re using rgb24 or rgb48 in SmartMatrix Library to store your colors, so there are wrapper functions in the layers that take the rgb24/rgb48 color, store it while Adafruit_GFX is doing the drawing, and pass it through to the actual drawPixel(rgb24)/drawPixel(rgb48) functions.

Backwards Compatibility

When compiling existing SmartMatrix Library 3.x sketches using FastLED, you will get errors unless you add explicit casts when assigning FastLED’s CRGB to rgb24. With the new uint16_t conversions for Adafruit_GFX, the compiler gets confused as to which type we want, even though this sketch doesn’t use the new layers. See FastLED_Functions for an example.

You will likely notice scrolling text isn't displaying properly if you use long strings with the new scrolling Layer, read on for more details:

Memory Allocation for Scrolling Layer

Previously, for scrolling text functionality, 1bpp was allocated for the viewable area (kMatrixWidth*kMatrixHeight), and each time the scrolling text moved on the screen, the visible text would be redrawn. This was inefficient in the amount of processor used per scrolling update, and as matrix sizes and fonts are getting larger it was enough to lower the overall refresh rate of the matrix. Now the string is drawn only once to a buffer sized to fit the string, but if there's not enough RAM allocated at compile time to hold a given string, it will only be partially drawn (from the top down until the allocated RAM is exhausted). The MultipleTextLayersGfx example is set up to show how to size your Layer to fit the string you want to scroll.

Using Adafruit_GFX Functions

Adafruit has an excellent reference on library functions that mostly applies to the SmartMatrix Library:
Adafruit Graphics Library - Adafruit Learning System

Note that Adafruit_GFX exclusively uses uint16_t colors in their documentation, but with the SmartMatrix Library GFX Layers you can use uint16_t, rgb24, or rgb48.

Getting Started:

1. Install Adafruit_GFX (1.3.0 or later)

• If you see errors like error: 'textsize_y' was not declared in this scope, upgrade Adafruit_GFX to 1.3.0 or later

2. Add #define USE_ADAFRUIT_GFX_LAYERS above #include <SmartMatrix.h> in your sketch

You can learn more about how the GFX Layers work through the examples:

• MultipleTextLayers: optionally uses Adafruit_GFX layers, improving refresh rate
• FeatureDemo: updated to support GFX Layers, noting that due to the long strings used in the demo, the scrolling text Layer needs more RAM allocated
• FastLED_Functions: add explicit cast from CRGB to rgb24.
• Example Adafruit_Gfx: shows how to use Adafruit_GFX functions with the new layers
• MultipleTextLayersGfx: Improved version of MultipleTextLayers, includes Adafruit_GFX fonts, and shows how to allocate the appropriate amount of space in the layer to display text

---

Todo: add a description of the setup code and layer functions here, as well as the utility functions (setRotation, setRefreshRate, setBrightness, getScreenWidth, getScreenHeight, getRefreshRate, getdmaBufferUnderrunFlag, getRefreshRateLoweredFlag, countFPS). Don't need an in depth description of the refresh API.

Some information can be found here, but is out of date:

https://github.com/pixelmatix/SmartMatrix/blob/master/MIGRATION.md

http://docs.pixelmatix.com/SmartMatrix/library.html

ESP32

• The ESP32 Platform is not fully supported like Teensy 3 and 4, and there aren't plans to complete all the features
• See ESP32 Port