Features

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) below. 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) below.

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.

Layers API

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

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