add circuitpython code

1 files changed, 1302 insertions, 0 deletions

diff --git a/circuitpython/lib/protomatter/src/core.c b/circuitpython/lib/protomatter/src/core.c
new file mode 100644
index 0000000..8428797
--- /dev/null
+++ b/circuitpython/lib/protomatter/src/core.c
@@ -0,0 +1,1302 @@
+/*!
+ * @file core.c
+ *
+ * Part of Adafruit's Protomatter library for HUB75-style RGB LED matrices.
+ *
+ * Adafruit invests time and resources providing this open source code,
+ * please support Adafruit and open-source hardware by purchasing
+ * products from Adafruit!
+ *
+ * Written by Phil "Paint Your Dragon" Burgess and Jeff Epler for
+ * Adafruit Industries, with contributions from the open source community.
+ *
+ * BSD license, all text here must be included in any redistribution.
+ *
+ */
+
+// Device- and environment-neutral core matrix-driving functionality.
+// See notes near top of arch/arch.h regarding assumptions of hardware
+// "common ground." If you find yourself doing an "#ifdef ARDUINO" or
+// "#ifdef _SAMD21_" in this file, STOP. Idea is that the code in this
+// file is neutral and portable (within aforementioned assumptions).
+// Nonportable elements should appear in arch.h. If arch.h functionality
+// is lacking, extend it there, do not go making device- or environment-
+// specific cases within this file.
+
+// Function names are intentionally a little obtuse, idea is that one writes
+// a more sensible wrapper around this for specific environments (e.g. the
+// Arduino stuff in Adafruit_Protomatter.cpp). The "_PM_" prefix on most
+// things hopefully makes function and variable name collisions much less
+// likely with one's own code.
+
+#include "core.h"      // enums and structs
+#include "arch/arch.h" // Do NOT include this in any other source files
+#include <stddef.h>
+#include <stdlib.h>
+#include <string.h>
+
+// Overall matrix refresh rate (frames/second) is a function of matrix width
+// and chain length, number of address lines, number of bit planes, CPU speed
+// and whether or not a GPIO toggle register is available. There is no "this
+// will run at X-frames-per-second" constant figure. You typically just have
+// to try it out and perhaps trade off some bit planes for refresh rate until
+// the image looks good and stable. Anything over 100 Hz is usually passable,
+// around 250 Hz is where things firm up. And while this could proceed higher
+// in some situations, the tradeoff is that faster rates use progressively
+// more CPU time (because it's timer interrupt based and not using DMA or
+// special peripherals). So a throttle is set here, an approximate maximum
+// frame rate which the software will attempt to avoid exceeding (but may
+// refresh slower than this, and in many cases will...just need to set an
+// upper limit to avoid excessive CPU load). An incredibly long comment block
+// for a single constant, thank you for coming to my TED talk!
+#define _PM_MAX_REFRESH_HZ 250 ///< Max matrix refresh rate
+
+// Time (in microseconds) to pause following any change in address lines
+// (individually or collectively). Some matrices respond slowly there...
+// must pause on change for matrix to catch up. Defined here (rather than
+// arch.h) because it's not architecture-specific.
+#define _PM_ROW_DELAY 8 ///< Delay time between row address line changes (ms)
+
+// These are the lowest-level functions for issing data to matrices.
+// There are three versions because it depends on how the six RGB data bits
+// (and clock bit) are arranged within a 32-bit PORT register. If all six
+// (seven) fit within one byte or word of the PORT, the library's memory
+// use (and corresponding data-issuing function) change. This will also have
+// an impact on parallel chains in the future, where the number of concurrent
+// RGB data bits isn't always six, but some multiple thereof (i.e. up to five
+// parallel outputs -- 30 RGB bits + clock -- on a 32-bit PORT, though that's
+// largely hypothetical as the chance of finding a PORT with that many bits
+// exposed and NOT interfering with other peripherals on a board is highly
+// improbable. But I could see four happening, maybe on a Grand Central or
+// other kitchen-sink board.
+static void blast_byte(Protomatter_core *core, uint8_t *data);
+static void blast_word(Protomatter_core *core, uint16_t *data);
+static void blast_long(Protomatter_core *core, uint32_t *data);
+
+#define _PM_clearReg(x)                                                        \
+  (*(volatile _PM_PORT_TYPE *)((x).clearReg) =                                 \
+       ((x).bit)) ///< Clear non-RGB-data-or-clock control line (_PM_pin type)
+#define _PM_setReg(x)                                                          \
+  (*(volatile _PM_PORT_TYPE *)((x).setReg) =                                   \
+       ((x).bit)) ///< Set non-RGB-data-or-clock control line (_PM_pin type)
+
+// Validate and populate vital elements of core structure.
+// Does NOT allocate core struct -- calling function must provide that.
+// (In the Arduino C++ library, it’s part of the Protomatter class.)
+ProtomatterStatus _PM_init(Protomatter_core *core, uint16_t bitWidth,
+                           uint8_t bitDepth, uint8_t rgbCount, uint8_t *rgbList,
+                           uint8_t addrCount, uint8_t *addrList,
+                           uint8_t clockPin, uint8_t latchPin, uint8_t oePin,
+                           bool doubleBuffer, int8_t tile, void *timer) {
+  if (!core)
+    return PROTOMATTER_ERR_ARG;
+
+  // bitDepth is NOT constrained here, handle in calling function
+  // (varies with implementation, e.g. GFX lib is max 6 bitplanes,
+  // but might be more or less elsewhere)
+  if (rgbCount > 5)
+    rgbCount = 5; // Max 5 in parallel (32-bit PORT)
+  if (addrCount > 5)
+    addrCount = 5; // Max 5 address lines (A-E)
+  if (!tile)
+    tile = 1; // Can't have zero vertical tiling. Single matrix is 1.
+
+#if defined(_PM_TIMER_DEFAULT)
+  // If NULL timer was passed in (the default case for the constructor),
+  // use default value from arch.h. For example, in the Arduino case it's
+  // tied to TC4 specifically.
+  if (timer == NULL)
+    timer = _PM_TIMER_DEFAULT;
+#else
+  if (timer == NULL)
+    return PROTOMATTER_ERR_ARG;
+#endif
+
+  core->timer = timer;
+  core->width = bitWidth; // Matrix chain width in bits (NOT including V tile)
+  core->tile = tile;      // Matrix chain vertical tiling
+  core->chainBits = bitWidth * abs(tile); // Total matrix chain bits
+  core->numPlanes = bitDepth;
+  core->parallel = rgbCount;
+  core->numAddressLines = addrCount;
+  core->clockPin = clockPin;
+  core->latch.pin = latchPin;
+  core->oe.pin = oePin;
+  core->doubleBuffer = doubleBuffer;
+  core->addr = NULL;
+  core->screenData = NULL;
+
+  // Make a copy of the rgbList and addrList tables in case they're
+  // passed from local vars on the stack or some other non-persistent
+  // source. screenData is NOT allocated here because data size (byte,
+  // word, long) is not known until the begin function evaluates all
+  // the pin bitmasks.
+
+  rgbCount *= 6; // Convert parallel count to pin count
+  if ((core->rgbPins = (uint8_t *)_PM_allocate(rgbCount * sizeof(uint8_t)))) {
+    if ((core->addr = (_PM_pin *)_PM_allocate(addrCount * sizeof(_PM_pin)))) {
+      memcpy(core->rgbPins, rgbList, rgbCount * sizeof(uint8_t));
+      for (uint8_t i = 0; i < addrCount; i++) {
+        core->addr[i].pin = addrList[i];
+      }
+      return PROTOMATTER_OK;
+    }
+    _PM_free(core->rgbPins);
+    core->rgbPins = NULL;
+  }
+  return PROTOMATTER_ERR_MALLOC;
+}
+
+// Allocate display buffers and populate additional elements.
+ProtomatterStatus _PM_begin(Protomatter_core *core) {
+  if (!core)
+    return PROTOMATTER_ERR_ARG;
+
+  if (!core->rgbPins) { // NULL if copy failed to allocate
+    return PROTOMATTER_ERR_MALLOC;
+  }
+
+  // Verify that rgbPins and clockPin are all on the same PORT. If not,
+  // return an error. Pin list is not freed; please call dealloc function.
+  // Also get bitmask of which bits within 32-bit PORT register are
+  // referenced.
+  uint8_t *port = (uint8_t *)_PM_portOutRegister(core->clockPin);
+#if defined(_PM_portToggleRegister)
+  // If a bit-toggle register is present, the clock pin is included
+  // in determining which bytes of the PORT register are used (and thus
+  // the data storage efficiency).
+  uint32_t bitMask = _PM_portBitMask(core->clockPin);
+#else
+  // If no bit-toggle register, clock pin can be on any bit, doesn't
+  // affect storage efficiency.
+  uint32_t bitMask = 0;
+#endif
+
+  for (uint8_t i = 0; i < core->parallel * 6; i++) {
+    uint8_t *p2 = (uint8_t *)_PM_portOutRegister(core->rgbPins[i]);
+    if (p2 != port) {
+      return PROTOMATTER_ERR_PINS;
+    }
+    bitMask |= _PM_portBitMask(core->rgbPins[i]);
+  }
+
+  // RGB + clock are on same port, we can proceed...
+
+  // Determine data type for internal representation. If all the data
+  // bitmasks (and possibly clock bitmask, depending whether toggle-bits
+  // register is present) are in the same byte, this can be stored more
+  // compact than if they're spread across a word or long.
+  uint8_t byteMask = 0;
+  if (bitMask & 0xFF000000)
+    byteMask |= 0b1000;
+  if (bitMask & 0x00FF0000)
+    byteMask |= 0b0100;
+  if (bitMask & 0x0000FF00)
+    byteMask |= 0b0010;
+  if (bitMask & 0x000000FF)
+    byteMask |= 0b0001;
+  switch (byteMask) {
+  case 0b0001: // If all PORT bits are in the same byte...
+  case 0b0010:
+  case 0b0100:
+  case 0b1000:
+    core->bytesPerElement = 1; // Use 8-bit PORT accesses.
+    break;
+  case 0b0011: // If all PORT bits in upper/lower word...
+  case 0b1100:
+    core->bytesPerElement = 2; // Use 16-bit PORT accesses.
+    // Although some devices might tolerate unaligned 16-bit accesses
+    // ('middle' word of 32-bit PORT), that is NOT handled here.
+    // It's a portability liability.
+    break;
+  default:                     // Any other situation...
+    core->bytesPerElement = 4; // Use 32-bit PORT accesses.
+    break;
+  }
+
+  // Planning for screen data allocation...
+  core->numRowPairs = 1 << core->numAddressLines;
+  uint8_t chunks = (core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize;
+  uint16_t columns = chunks * _PM_chunkSize; // Padded matrix width
+  uint32_t screenBytes =
+      columns * core->numRowPairs * core->numPlanes * core->bytesPerElement;
+
+  core->bufferSize = screenBytes; // Bytes per matrix buffer (1 or 2)
+  if (core->doubleBuffer)
+    screenBytes *= 2; // Total for matrix buffer(s)
+  uint32_t rgbMaskBytes = core->parallel * 6 * core->bytesPerElement;
+
+  // Allocate matrix buffer(s). Don't worry about the return type...
+  // though we might be using words or longs for certain pin configs,
+  // _PM_allocate() by definition always aligns to the longest type.
+  if (!(core->screenData =
+            (uint8_t *)_PM_allocate(screenBytes + rgbMaskBytes))) {
+    return PROTOMATTER_ERR_MALLOC;
+  }
+
+  // rgbMask data follows the matrix buffer(s)
+  core->rgbMask = core->screenData + screenBytes;
+
+#if !defined(_PM_portToggleRegister)
+  // Clear entire screenData buffer so there's no cruft in any pad bytes
+  // (if using toggle register, each is set to clockMask below instead).
+  memset(core->screenData, 0, screenBytes);
+#endif
+
+  // Figure out clockMask and rgbAndClockMask, clear matrix buffers
+  if (core->bytesPerElement == 1) {
+    core->portOffset = _PM_byteOffset(core->rgbPins[0]);
+#if defined(_PM_portToggleRegister) && !defined(_PM_STRICT_32BIT_IO)
+    // Clock and rgbAndClockMask are 8-bit values
+    core->clockMask = _PM_portBitMask(core->clockPin) >> (core->portOffset * 8);
+    core->rgbAndClockMask =
+        (bitMask >> (core->portOffset * 8)) | core->clockMask;
+    memset(core->screenData, core->clockMask, screenBytes);
+#else
+    // Clock and rgbAndClockMask are 32-bit values
+    core->clockMask = _PM_portBitMask(core->clockPin);
+    core->rgbAndClockMask = bitMask | core->clockMask;
+#endif
+    for (uint8_t i = 0; i < core->parallel * 6; i++) {
+      ((uint8_t *)core->rgbMask)[i] = // Pin bitmasks are 8-bit
+          _PM_portBitMask(core->rgbPins[i]) >> (core->portOffset * 8);
+    }
+  } else if (core->bytesPerElement == 2) {
+    core->portOffset = _PM_wordOffset(core->rgbPins[0]);
+#if defined(_PM_portToggleRegister) && !defined(_PM_STRICT_32BIT_IO)
+    // Clock and rgbAndClockMask are 16-bit values
+    core->clockMask =
+        _PM_portBitMask(core->clockPin) >> (core->portOffset * 16);
+    core->rgbAndClockMask =
+        (bitMask >> (core->portOffset * 16)) | core->clockMask;
+    uint32_t elements = screenBytes / 2;
+    for (uint32_t i = 0; i < elements; i++) {
+      ((uint16_t *)core->screenData)[i] = core->clockMask;
+    }
+#else
+    // Clock and rgbAndClockMask are 32-bit values
+    core->clockMask = _PM_portBitMask(core->clockPin);
+    core->rgbAndClockMask = bitMask | core->clockMask;
+#if defined(_PM_portToggleRegister)
+    // TO DO: this ifdef and the one above can probably be wrapped up
+    // in a more cohesive case. Think something similar will be needed
+    // for the byte case. Will need Teensy 4.1 to test.
+    uint32_t elements = screenBytes / 2;
+    uint16_t mask = core->clockMask >> (core->portOffset * 16);
+    for (uint32_t i = 0; i < elements; i++) {
+      ((uint16_t *)core->screenData)[i] = mask;
+    }
+#endif
+#endif
+    for (uint8_t i = 0; i < core->parallel * 6; i++) {
+      ((uint16_t *)core->rgbMask)[i] = // Pin bitmasks are 16-bit
+          _PM_portBitMask(core->rgbPins[i]) >> (core->portOffset * 16);
+    }
+  } else {
+    core->portOffset = 0;
+    core->clockMask = _PM_portBitMask(core->clockPin);
+    core->rgbAndClockMask = bitMask | core->clockMask;
+#if defined(_PM_portToggleRegister)
+    uint32_t elements = screenBytes / 4;
+    for (uint32_t i = 0; i < elements; i++) {
+      ((uint32_t *)core->screenData)[i] = core->clockMask;
+    }
+#endif
+    for (uint8_t i = 0; i < core->parallel * 6; i++) {
+      ((uint32_t *)core->rgbMask)[i] = // Pin bitmasks are 32-bit
+          _PM_portBitMask(core->rgbPins[i]);
+    }
+  }
+
+  // Estimate minimum bitplane #0 period for _PM_MAX_REFRESH_HZ rate.
+  uint32_t minPeriodPerFrame = _PM_timerFreq / _PM_MAX_REFRESH_HZ;
+  uint32_t minPeriodPerLine = minPeriodPerFrame / core->numRowPairs;
+  core->minPeriod = minPeriodPerLine / ((1 << core->numPlanes) - 1);
+  if (core->minPeriod < _PM_minMinPeriod) {
+    core->minPeriod = _PM_minMinPeriod;
+  }
+  core->bitZeroPeriod = core->minPeriod;
+  // Actual frame rate may be lower than this...it's only an estimate
+  // and does not factor in things like address line selection delays
+  // or interrupt overhead. That's OK, just don't want to exceed this
+  // rate, as it'll eat all the CPU cycles.
+
+  core->activeBuffer = 0;
+
+  // Configure pins as outputs and initialize their states.
+
+  core->latch.setReg = _PM_portSetRegister(core->latch.pin);
+  core->latch.clearReg = _PM_portClearRegister(core->latch.pin);
+  core->latch.bit = _PM_portBitMask(core->latch.pin);
+  core->oe.setReg = _PM_portSetRegister(core->oe.pin);
+  core->oe.clearReg = _PM_portClearRegister(core->oe.pin);
+  core->oe.bit = _PM_portBitMask(core->oe.pin);
+
+  _PM_pinOutput(core->clockPin);
+  _PM_pinLow(core->clockPin); // Init clock LOW
+  _PM_pinOutput(core->latch.pin);
+  _PM_pinLow(core->latch.pin); // Init latch LOW
+  _PM_pinOutput(core->oe.pin);
+  _PM_pinHigh(core->oe.pin); // Init OE HIGH (disable output)
+
+  for (uint8_t i = 0; i < core->parallel * 6; i++) {
+    _PM_pinOutput(core->rgbPins[i]);
+    _PM_pinLow(core->rgbPins[i]);
+  }
+#if defined(_PM_portToggleRegister)
+  core->addrPortToggle = _PM_portToggleRegister(core->addr[0].pin);
+  core->singleAddrPort = 1;
+#endif
+  core->prevRow = (1 << core->numAddressLines) - 2;
+  for (uint8_t line = 0, bit = 1; line < core->numAddressLines;
+       line++, bit <<= 1) {
+    core->addr[line].setReg = _PM_portSetRegister(core->addr[line].pin);
+    core->addr[line].clearReg = _PM_portClearRegister(core->addr[line].pin);
+    core->addr[line].bit = _PM_portBitMask(core->addr[line].pin);
+    _PM_pinOutput(core->addr[line].pin);
+    if (core->prevRow & bit) {
+      _PM_pinHigh(core->addr[line].pin);
+    } else {
+      _PM_pinLow(core->addr[line].pin);
+    }
+#if defined(_PM_portToggleRegister)
+    // If address pin on different port than addr 0, no singleAddrPort.
+    if (_PM_portToggleRegister(core->addr[line].pin) != core->addrPortToggle) {
+      core->singleAddrPort = 0;
+    }
+#endif
+  }
+
+  // Get pointers to bit set and clear registers (and toggle, if present)
+  core->setReg = (uint8_t *)_PM_portSetRegister(core->clockPin);
+  core->clearReg = (uint8_t *)_PM_portClearRegister(core->clockPin);
+#if defined(_PM_portToggleRegister)
+  core->toggleReg = (uint8_t *)_PM_portToggleRegister(core->clockPin);
+#endif
+
+  // Reset plane/row counters, config and start timer
+  _PM_resume(core);
+
+  return PROTOMATTER_OK;
+}
+
+// Disable (but do not deallocate) a Protomatter matrix. Disables matrix by
+// setting OE pin HIGH and writing all-zero data to matrix shift registers,
+// so it won't halt with lit LEDs.
+void _PM_stop(Protomatter_core *core) {
+  if ((core)) {
+    // If _PM_begin failed, this will be a NULL pointer.  Stop early,
+    // none of the other "stop" operations make sense
+    if (!core->screenData) {
+      return;
+    }
+    while (core->swapBuffers)
+      ;                         // Wait for any pending buffer swap
+    _PM_timerStop(core->timer); // Halt timer
+    _PM_setReg(core->oe);       // Set OE HIGH (disable output)
+    // So, in PRINCIPLE, setting OE high would be sufficient...
+    // but in case that pin is shared with another function such
+    // as the onloard LED (which pulses during bootloading) let's
+    // also clear out the matrix shift registers for good measure.
+    // Set all RGB pins LOW...
+    for (uint8_t i = 0; i < core->parallel * 6; i++) {
+      _PM_pinLow(core->rgbPins[i]);
+    }
+    // Clock out bits (just need to toggle clock with RGBs held low)
+    for (uint32_t i = 0; i < core->chainBits; i++) {
+      _PM_pinHigh(core->clockPin);
+      _PM_clockHoldHigh;
+      _PM_pinLow(core->clockPin);
+      _PM_clockHoldLow;
+    }
+    // Latch data
+    _PM_setReg(core->latch);
+    _PM_clearReg(core->latch);
+  }
+}
+
+void _PM_resume(Protomatter_core *core) {
+  if ((core)) {
+    // Init plane & row to max values so they roll over on 1st interrupt
+    core->plane = core->numPlanes - 1;
+    core->row = core->numRowPairs - 1;
+    core->prevRow = (core->numRowPairs > 1) ? (core->row - 1) : 1;
+    core->swapBuffers = 0;
+    core->frameCount = 0;
+
+    for (uint8_t line = 0, bit = 1; line < core->numAddressLines;
+         line++, bit <<= 1) {
+      _PM_pinOutput(core->addr[line].pin);
+      if (core->prevRow & bit) {
+        _PM_pinHigh(core->addr[line].pin);
+      } else {
+        _PM_pinLow(core->addr[line].pin);
+      }
+    }
+
+    _PM_timerInit(core->timer);        // Configure timer
+    _PM_timerStart(core->timer, 1000); // Start timer
+  }
+}
+
+// Free memory associated with core structure. Does NOT dealloc struct.
+void _PM_deallocate(Protomatter_core *core) {
+  if ((core)) {
+    _PM_stop(core);
+    // TO DO: Set all pins back to inputs here?
+    if (core->screenData)
+      _PM_free(core->screenData);
+    if (core->addr)
+      _PM_free(core->addr);
+    if (core->rgbPins) {
+      _PM_free(core->rgbPins);
+      core->rgbPins = NULL;
+    }
+  }
+}
+
+// ISR function (in arch.h) calls this function which it extern'd.
+// Profuse apologies for the ESP32-specific IRAM_ATTR here -- the goal was
+// for all architecture-specific detauls to be in arch.h -- but the need
+// for one here caught me off guard. So, in arch.h, for all non-ESP32
+// devices, IRAM_ATTR is defined to nothing and is ignored here. If any
+// future architectures have their own attribute for making a function
+// RAM-resident, #define IRAM_ATTR to that in the corresponding device-
+// specific section of arch.h. Sorry. :/
+// Any functions called by this function should also be IRAM_ATTR'd.
+IRAM_ATTR void _PM_row_handler(Protomatter_core *core) {
+
+  _PM_setReg(core->oe); // Disable LED output
+
+  // ESP32 requires this next line, but not wanting to put arch-specific
+  // ifdefs in this code...it's a trivial operation so just do it.
+  // Latch is already clear at this point, but we go through the motions
+  // to clear it again in order to sync up the setReg(OE) above with the
+  // setReg(latch) that follows. Reason being, bit set/clear operations
+  // on ESP32 aren't truly atomic, and if those two pins are on the same
+  // port (quite common) the second setReg will be ignored. The nonsense
+  // clearReg is used to sync up the two setReg operations. See also the
+  // ESP32-specific PEW define in arch.h, same deal.
+  _PM_clearReg(core->latch);
+
+  _PM_setReg(core->latch);
+  (void)_PM_timerStop(core->timer);
+  uint8_t prevPlane = core->plane; // Save that plane # for later timing
+  _PM_clearReg(core->latch);       // (split to add a few cycles)
+
+  if (prevPlane == 0) { // Plane 0 just finished loading
+#if defined(_PM_portToggleRegister)
+    // If all address lines are on a single PORT (and bit toggle is
+    // available), do address line change all at once. Even doing all
+    // this math takes MUCH less time than the delays required when
+    // doing line-by-line changes.
+    if (core->singleAddrPort) {
+      // Make bitmasks of prior and new row bits
+      uint32_t priorBits = 0, newBits = 0;
+      for (uint8_t line = 0, bit = 1; line < core->numAddressLines;
+           line++, bit <<= 1) {
+        if (core->row & bit) {
+          newBits |= core->addr[line].bit;
+        }
+        if (core->prevRow & bit) {
+          priorBits |= core->addr[line].bit;
+        }
+      }
+      *(volatile _PM_PORT_TYPE *)core->addrPortToggle = newBits ^ priorBits;
+      _PM_delayMicroseconds(_PM_ROW_DELAY);
+    } else {
+#endif
+      // Configure row address lines individually, making changes
+      // (with delays) only where necessary.
+      for (uint8_t line = 0, bit = 1; line < core->numAddressLines;
+           line++, bit <<= 1) {
+        if ((core->row & bit) != (core->prevRow & bit)) {
+          if (core->row & bit) { // Set addr line high
+            _PM_setReg(core->addr[line]);
+          } else { // Set addr line low
+            _PM_clearReg(core->addr[line]);
+          }
+          _PM_delayMicroseconds(_PM_ROW_DELAY);
+        }
+      }
+#if defined(_PM_portToggleRegister)
+    }
+#endif
+    core->prevRow = core->row;
+  }
+
+  // Advance bitplane index and/or row as necessary
+  if (++core->plane >= core->numPlanes) {   // Next data bitplane, or
+    core->plane = 0;                        // roll over bitplane to start
+    if (++core->row >= core->numRowPairs) { // Next row, or
+      core->row = 0;                        // roll over row to start
+      // Switch matrix buffers if due (only if double-buffered)
+      if (core->swapBuffers) {
+        core->activeBuffer = 1 - core->activeBuffer;
+        core->swapBuffers = 0; // Swapped!
+      }
+      core->frameCount++;
+    }
+  }
+
+  // core->plane now is index of data to issue, NOT data to display.
+  // 'prevPlane' is the previously-loaded data, which gets displayed
+  // now while the next plane data is loaded.
+
+  // Set timer and enable LED output for data loaded on PRIOR pass:
+  _PM_timerStart(core->timer, core->bitZeroPeriod << prevPlane);
+  _PM_delayMicroseconds(1); // Appease Teensy4
+  _PM_clearReg(core->oe);   // Enable LED output
+
+  uint32_t elementsPerLine =
+      _PM_chunkSize * ((core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize);
+  uint32_t srcOffset = elementsPerLine *
+                       (core->numPlanes * core->row + core->plane) *
+                       core->bytesPerElement;
+  if (core->doubleBuffer) {
+    srcOffset += core->bufferSize * core->activeBuffer;
+  }
+
+  if (core->bytesPerElement == 1) {
+    blast_byte(core, (uint8_t *)(core->screenData + srcOffset));
+  } else if (core->bytesPerElement == 2) {
+    blast_word(core, (uint16_t *)(core->screenData + srcOffset));
+  } else {
+    blast_long(core, (uint32_t *)(core->screenData + srcOffset));
+  }
+
+  // core->plane data is now loaded, will be shown on NEXT pass
+
+  // On the last (longest) bitplane (note that 'plane' has already wrapped
+  // around earlier, so a value of 0 here indicates longest plane), take
+  // note of the elapsed timer value at this point...that's the number of
+  // cycles required to issue (not necessarily display) data for one plane,
+  // and the bare minimum display duration allowed for plane 0.
+  if ((core->numPlanes > 1) && (core->plane == 0)) {
+    // Determine number of timer cycles taken to issue the data.
+    // It can vary slightly if heavy interrupts happen, things like that.
+    // Timer is still running and counting up at this point.
+    uint32_t elapsed = _PM_timerGetCount(core->timer);
+    // Nudge the plane-zero time up or down (filtering to avoid jitter)
+    core->bitZeroPeriod = ((core->bitZeroPeriod * 7) + elapsed + 4) / 8;
+    // But don't allow it to drop below the minimum period calculated during
+    // begin(), that's a hard limit and would just waste cycles.
+    if (core->bitZeroPeriod < core->minPeriod) {
+      core->bitZeroPeriod = core->minPeriod;
+    }
+  }
+}
+
+// Innermost data-stuffing loop functions
+
+// The presence of a bit-toggle register can make the data-stuffing loop a
+// fair bit faster (2 PORT accesses per column vs 3). But ironically, some
+// devices (e.g. SAMD51) can outpace the matrix max CLK speed, so we slow
+// them down with a few NOPs. These are defined in arch.h as needed.
+// _PM_clockHoldLow is whatever code necessary to delay the clock rise
+// after data is placed on the PORT. _PM_clockHoldHigh is code for delay
+// before setting the clock back low. If undefined, nothing goes there.
+
+#if !defined(PEW) // arch.h can define a custom PEW if needed (e.g. ESP32)
+
+#if !defined(_PM_STRICT_32BIT_IO) // Partial access to 32-bit GPIO OK
+
+#if defined(_PM_portToggleRegister)
+#define PEW                                                                    \
+  *toggle = *data++; /* Toggle in new data + toggle clock low */               \
+  _PM_clockHoldLow;                                                            \
+  *toggle = clock; /* Toggle clock high */                                     \
+  _PM_clockHoldHigh;
+#else
+#define PEW                                                                    \
+  *set = *data++; /* Set RGB data high */                                      \
+  _PM_clockHoldLow;                                                            \
+  *set_full = clock; /* Set clock high */                                      \
+  _PM_clockHoldHigh;                                                           \
+  *clear_full = rgbclock; /* Clear RGB data + clock */                         \
+  ///< Bitbang one set of RGB data bits to matrix
+#endif
+
+#else // ONLY 32-bit GPIO
+
+#if defined(_PM_portToggleRegister)
+#define PEW                                                                    \
+  *toggle = *data++ << shift; /* Toggle in new data + toggle clock low */      \
+  _PM_clockHoldLow;                                                            \
+  *toggle = clock; /* Toggle clock high */                                     \
+  _PM_clockHoldHigh;
+#else
+#define PEW                                                                    \
+  *set = *data++ << shift; /* Set RGB data high */                             \
+  _PM_clockHoldLow;                                                            \
+  *set = clock; /* Set clock high */                                           \
+  _PM_clockHoldHigh;                                                           \
+  *clear_full = rgbclock; /* Clear RGB data + clock */                         \
+  ///< Bitbang one set of RGB data bits to matrix
+#endif
+
+#endif // end 32-bit GPIO
+
+#endif // end PEW
+
+#if _PM_chunkSize == 1
+#define PEW_UNROLL PEW
+#elif _PM_chunkSize == 2
+#define PEW_UNROLL PEW PEW ///< 2-way PEW unroll
+#elif _PM_chunkSize == 4
+#define PEW_UNROLL PEW PEW PEW PEW ///< 4-way PEW unroll
+#elif _PM_chunkSize == 8
+#define PEW_UNROLL PEW PEW PEW PEW PEW PEW PEW PEW ///< 8-way PEW unroll
+#elif _PM_chunkSize == 16
+#define PEW_UNROLL                                                             \
+  PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW
+#elif _PM_chunkSize == 32
+#define PEW_UNROLL                                                             \
+  PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW  \
+      PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW
+#elif _PM_chunkSize == 64
+#define PEW_UNROLL                                                             \
+  PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW  \
+      PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW  \
+          PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW  \
+              PEW PEW PEW PEW PEW PEW PEW PEW PEW PEW
+#else
+#error "Unimplemented _PM_chunkSize value"
+#endif
+
+// There are THREE COPIES of the following function -- one each for byte,
+// word and long. If changes are made in any one of them, the others MUST
+// be updated to match! (Decided against using macro tricks for the
+// function, too often ends in disaster...but must be vigilant in the
+// three-function maintenance then.)
+
+IRAM_ATTR static void blast_byte(Protomatter_core *core, uint8_t *data) {
+#if !defined(_PM_STRICT_32BIT_IO) // Partial access to 32-bit GPIO OK
+
+#if defined(_PM_portToggleRegister)
+  // If here, it was established in begin() that the RGB data bits and
+  // clock are all within the same byte of a PORT register, else we'd be
+  // in the word- or long-blasting functions now. So we just need an
+  // 8-bit pointer to the PORT.
+  volatile uint8_t *toggle =
+      (volatile uint8_t *)core->toggleReg + core->portOffset;
+#else
+  // No-toggle version is a little different. If here, RGB data is all
+  // in one byte of PORT register, clock can be any bit in 32-bit PORT.
+  volatile uint8_t *set;              // For RGB data set
+  volatile _PM_PORT_TYPE *set_full;   // For clock set
+  volatile _PM_PORT_TYPE *clear_full; // For RGB data + clock clear
+  set = (volatile uint8_t *)core->setReg + core->portOffset;
+  set_full = (volatile _PM_PORT_TYPE *)core->setReg;
+  clear_full = (volatile _PM_PORT_TYPE *)core->clearReg;
+  _PM_PORT_TYPE rgbclock = core->rgbAndClockMask; // RGB + clock bit
+#endif
+  _PM_PORT_TYPE clock = core->clockMask; // Clock bit
+  uint8_t chunks = (core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize;
+
+  // PORT has already been initialized with RGB data + clock bits
+  // all LOW, so we don't need to initialize that state here.
+
+  while (chunks--) {
+    PEW_UNROLL // _PM_chunkSize RGB+clock writes
+  }
+
+#if defined(_PM_portToggleRegister)
+  // Want the PORT left with RGB data and clock LOW on function exit
+  // (so it's easier to see on 'scope, and to prime it for the next call).
+  // This is implicit in the no-toggle case (due to how the PEW macro
+  // works), but toggle case requires explicitly clearing those bits.
+  // rgbAndClockMask is an 8-bit value when toggling, hence offset here.
+  *((volatile uint8_t *)core->clearReg + core->portOffset) =
+      core->rgbAndClockMask;
+#endif
+
+#else // ONLY 32-bit GPIO
+
+#if defined(_PM_portToggleRegister)
+  volatile _PM_PORT_TYPE *toggle = (volatile _PM_PORT_TYPE *)core->toggleReg;
+#else
+  volatile _PM_PORT_TYPE *set = (volatile _PM_PORT_TYPE *)core->setReg;
+  volatile _PM_PORT_TYPE *clear_full = (volatile _PM_PORT_TYPE *)core->clearReg;
+  _PM_PORT_TYPE rgbclock = core->rgbAndClockMask; // RGB + clock bit
+#endif
+  _PM_PORT_TYPE clock = core->clockMask; // Clock bit
+  uint8_t shift = core->portOffset * 8;
+  uint8_t chunks = (core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize;
+
+  // PORT has already been initialized with RGB data + clock bits
+  // all LOW, so we don't need to initialize that state here.
+
+  while (chunks--) {
+    PEW_UNROLL // _PM_chunkSize RGB+clock writes
+  }
+
+#if defined(_PM_portToggleRegister)
+  *((volatile uint32_t *)core->clearReg) = core->rgbAndClockMask;
+#endif
+
+#endif // 32-bit GPIO
+}
+
+IRAM_ATTR static void blast_word(Protomatter_core *core, uint16_t *data) {
+#if !defined(_PM_STRICT_32BIT_IO) // Partial access to 32-bit GPIO OK
+
+#if defined(_PM_portToggleRegister)
+  // See notes above -- except now 16-bit word in PORT.
+  volatile uint16_t *toggle =
+      (volatile uint16_t *)core->toggleReg + core->portOffset;
+#else
+  volatile uint16_t *set;                         // For RGB data set
+  volatile _PM_PORT_TYPE *set_full;               // For clock set
+  volatile _PM_PORT_TYPE *clear_full;             // For RGB data + clock clear
+  set = (volatile uint16_t *)core->setReg + core->portOffset;
+  set_full = (volatile _PM_PORT_TYPE *)core->setReg;
+  clear_full = (volatile _PM_PORT_TYPE *)core->clearReg;
+  _PM_PORT_TYPE rgbclock = core->rgbAndClockMask; // RGB + clock bit
+#endif
+  _PM_PORT_TYPE clock = core->clockMask; // Clock bit
+  uint8_t chunks = (core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize;
+  while (chunks--) {
+    PEW_UNROLL // _PM_chunkSize RGB+clock writes
+  }
+#if defined(_PM_portToggleRegister)
+  // rgbAndClockMask is a 16-bit value when toggling, hence offset here.
+  *((volatile uint16_t *)core->clearReg + core->portOffset) =
+      core->rgbAndClockMask;
+#endif
+
+#else // ONLY 32-bit GPIO
+
+#if defined(_PM_portToggleRegister)
+  volatile _PM_PORT_TYPE *toggle = (volatile _PM_PORT_TYPE *)core->toggleReg;
+#else
+  volatile _PM_PORT_TYPE *set = (volatile _PM_PORT_TYPE *)core->setReg;
+  volatile _PM_PORT_TYPE *clear_full = (volatile _PM_PORT_TYPE *)core->clearReg;
+  _PM_PORT_TYPE rgbclock = core->rgbAndClockMask; // RGB + clock bit
+#endif
+  _PM_PORT_TYPE clock = core->clockMask; // Clock bit
+  uint8_t shift = core->portOffset * 16;
+  uint8_t chunks = (core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize;
+  while (chunks--) {
+    PEW_UNROLL // _PM_chunkSize RGB+clock writes
+  }
+#if defined(_PM_portToggleRegister)
+  *((volatile _PM_PORT_TYPE *)core->clearReg) = core->rgbAndClockMask;
+#endif
+
+#endif // 32-bit GPIO
+}
+
+IRAM_ATTR static void blast_long(Protomatter_core *core, uint32_t *data) {
+#if defined(_PM_portToggleRegister)
+  // See notes above -- except now full 32-bit PORT.
+  volatile uint32_t *toggle = (volatile uint32_t *)core->toggleReg;
+#else
+  // Note in this case two copies exist of the PORT set register.
+  // The optimizer will most likely simplify this; leaving as-is, not
+  // wanting a special case of the PEW macro due to divergence risk.
+  volatile uint32_t *set;           // For RGB data set
+#if !defined(_PM_STRICT_32BIT_IO)
+  volatile _PM_PORT_TYPE *set_full; // For clock set
+  set_full = (volatile _PM_PORT_TYPE *)core->setReg;
+#endif
+  volatile _PM_PORT_TYPE *clear_full; // For RGB data + clock clear
+  set = (volatile uint32_t *)core->setReg;
+  clear_full = (volatile _PM_PORT_TYPE *)core->clearReg;
+  _PM_PORT_TYPE rgbclock = core->rgbAndClockMask; // RGB + clock bit
+#endif
+  _PM_PORT_TYPE clock = core->clockMask; // Clock bit
+#if defined(_PM_STRICT_32BIT_IO)
+  uint8_t shift = 0;
+#endif
+  uint8_t chunks = (core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize;
+  while (chunks--) {
+    PEW_UNROLL // _PM_chunkSize RGB+clock writes
+  }
+#if defined(_PM_portToggleRegister)
+  *(volatile uint32_t *)core->clearReg = core->rgbAndClockMask;
+#endif
+}
+
+// Returns current value of frame counter and resets its value to zero.
+// Two calls to this, timed one second apart (or use math with other
+// intervals), can be used to get a rough frames-per-second value for
+// the matrix (since this is difficult to estimate beforehand).
+uint32_t _PM_getFrameCount(Protomatter_core *core) {
+  uint32_t count = 0;
+  if ((core)) {
+    count = core->frameCount;
+    core->frameCount = 0;
+  }
+  return count;
+}
+
+void _PM_swapbuffer_maybe(Protomatter_core *core) {
+  if (core->doubleBuffer) {
+    core->swapBuffers = 1;
+    // To avoid overwriting data on the matrix, don't return
+    // until the timer ISR has performed the swap at the right time.
+    while (core->swapBuffers)
+      ;
+  }
+}
+
+#if defined(ARDUINO) || defined(CIRCUITPY)
+
+// Arduino and CircuitPython happen to use the same internal canvas
+// representation.
+
+// 16-bit (565) color conversion functions go here (rather than in the
+// Arduino lib .cpp) because knowledge is required of chunksize and the
+// toggle register (or lack thereof), which are only known to this file,
+// not the .cpp or anywhere else. However...this file knows nothing of
+// the GFXcanvas16 type (from Adafruit_GFX...another C++ lib), so the
+// .cpp just passes down some pointers and minimal info about the canvas
+// buffer. It's probably not ideal but this is my life now, oh well.
+
+// Different runtime environments (which might not use the 565 canvas
+// format) will need their own conversion functions.
+
+// There are THREE COPIES of the following function -- one each for byte,
+// word and long. If changes are made in any one of them, the others MUST
+// be updated to match! Note that they are not simple duplicates of each
+// other. The byte case, for example, doesn't need to handle parallel
+// matrix chains (matrix data can only be byte-sized if one chain).
+
+// width argument comes from GFX canvas width, which may be less than
+// core's bitWidth (due to padding). height isn't needed, it can be
+// inferred from core->numRowPairs and core->tile.
+__attribute__((noinline)) void _PM_convert_565_byte(Protomatter_core *core,
+                                                    const uint16_t *source,
+                                                    uint16_t width) {
+  uint8_t *pinMask = (uint8_t *)core->rgbMask; // Pin bitmasks
+  uint8_t *dest = (uint8_t *)core->screenData;
+  if (core->doubleBuffer) {
+    dest += core->bufferSize * (1 - core->activeBuffer);
+  }
+
+#if defined(_PM_portToggleRegister)
+#if !defined(_PM_STRICT_32BIT_IO)
+  // core->clockMask mask is already an 8-bit value
+  uint8_t clockMask = core->clockMask;
+#else
+  // core->clockMask mask is 32-bit, shift down to 8-bit for this func.
+  uint8_t clockMask = core->clockMask >> (core->portOffset * 8);
+#endif
+#endif
+
+  // No need to clear matrix buffer, loops below do a full overwrite
+  // (except for any scanline pad, which was already initialized in the
+  // begin() function and won't be touched here).
+
+  // Determine matrix bytes per bitplane & row (row pair really):
+
+  // Size of 1 plane of row pair (across full chain / tile set)
+  uint32_t bitplaneSize =
+      _PM_chunkSize * ((core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize);
+  uint8_t pad = bitplaneSize - core->chainBits; // Plane-start pad
+
+  // Skip initial scanline padding if present (HUB75 matrices shift data
+  // in from right-to-left, so if we need scanline padding it occurs at
+  // the start of a line, rather than the usual end). Destination pointer
+  // passed in already handles double-buffer math, so we don't need to
+  // handle that here, just the pad...
+  dest += pad;
+
+  uint32_t initialRedBit, initialGreenBit, initialBlueBit;
+  if (core->numPlanes == 6) {
+    // If numPlanes is 6, red and blue are expanded from 5 to 6 bits.
+    // This involves duplicating the MSB of the 5-bit value to the LSB
+    // of its corresponding 6-bit value...or in this case, bitmasks for
+    // red and blue are initially assigned to canvas MSBs, while green
+    // starts at LSB (because it's already 6-bit). Inner loop below then
+    // wraps red & blue after the first bitplane.
+    initialRedBit = 0b1000000000000000;   // MSB red
+    initialGreenBit = 0b0000000000100000; // LSB green
+    initialBlueBit = 0b0000000000010000;  // MSB blue
+  } else {
+    // If numPlanes is 1 to 5, no expansion is needed, and one or all
+    // three color components might be decimated by some number of bits.
+    // The initial bitmasks are set to the components' numPlanesth bit
+    // (e.g. for 5 planes, start at red & blue bit #0, green bit #1,
+    // for 4 planes, everything starts at the next bit up, etc.).
+    uint8_t shiftLeft = 5 - core->numPlanes;
+    initialRedBit = 0b0000100000000000 << shiftLeft;
+    initialGreenBit = 0b0000000001000000 << shiftLeft;
+    initialBlueBit = 0b0000000000000001 << shiftLeft;
+  }
+
+  // This works sequentially-ish through the destination buffer,
+  // reading from the canvas source pixels in repeated passes,
+  // beginning from the least bit.
+  for (uint8_t row = 0; row < core->numRowPairs; row++) {
+    uint32_t redBit = initialRedBit;
+    uint32_t greenBit = initialGreenBit;
+    uint32_t blueBit = initialBlueBit;
+    for (uint8_t plane = 0; plane < core->numPlanes; plane++) {
+#if defined(_PM_portToggleRegister)
+      uint8_t prior = clockMask; // Set clock bit on 1st out
+#endif
+      uint8_t *d2 = dest; // Incremented per-pixel across all tiles
+
+      // Work from bottom tile to top, because data is issued in that order
+      for (int8_t tile = abs(core->tile) - 1; tile >= 0; tile--) {
+        const uint16_t *upperSrc, *lowerSrc; // Canvas scanline pointers
+        int16_t srcIdx;
+        int8_t srcInc;
+
+        // Source pointer to tile's upper-left pixel
+        const uint16_t *srcTileUL =
+            source + tile * width * core->numRowPairs * 2;
+        if ((tile & 1) && (core->tile < 0)) {
+          // Special handling for serpentine tiles
+          lowerSrc = srcTileUL + width * (core->numRowPairs - 1 - row);
+          upperSrc = lowerSrc + width * core->numRowPairs;
+          srcIdx = width - 1; // Work right to left
+          srcInc = -1;
+        } else {
+          // Progressive tile
+          upperSrc = srcTileUL + width * row;              // Top row
+          lowerSrc = upperSrc + width * core->numRowPairs; // Bottom row
+          srcIdx = 0;                                      // Left to right
+          srcInc = 1;
+        }
+
+        for (uint16_t x = 0; x < width; x++, srcIdx += srcInc) {
+          uint16_t upperRGB = upperSrc[srcIdx]; // Pixel in upper half
+          uint16_t lowerRGB = lowerSrc[srcIdx]; // Pixel in lower half
+          uint8_t result = 0;
+          if (upperRGB & redBit)
+            result |= pinMask[0];
+          if (upperRGB & greenBit)
+            result |= pinMask[1];
+          if (upperRGB & blueBit)
+            result |= pinMask[2];
+          if (lowerRGB & redBit)
+            result |= pinMask[3];
+          if (lowerRGB & greenBit)
+            result |= pinMask[4];
+          if (lowerRGB & blueBit)
+            result |= pinMask[5];
+#if defined(_PM_portToggleRegister)
+          *d2++ = result ^ prior;
+          prior = result | clockMask; // Set clock bit on next out
+#else
+          *d2++ = result;
+#endif
+        } // end x
+      }   // end tile
+
+      greenBit <<= 1;
+      if (plane || (core->numPlanes < 6)) {
+        // In most cases red & blue bit scoot 1 left...
+        redBit <<= 1;
+        blueBit <<= 1;
+      } else {
+        // Exception being after bit 0 with 6-plane display,
+        // in which case they're reset to red & blue LSBs
+        // (so 5-bit colors are expanded to 6 bits).
+        redBit = 0b0000100000000000;
+        blueBit = 0b0000000000000001;
+      }
+#if defined(_PM_portToggleRegister)
+      // If using bit-toggle register, erase the toggle bit on the
+      // first element of each bitplane & row pair. The matrix-driving
+      // interrupt functions correspondingly set the clock low before
+      // finishing. This is all done for legibility on oscilloscope --
+      // so idle clock appears LOW -- but really the matrix samples on
+      // a rising edge and we could leave it high, but at this stage
+      // in development just want the scope "readable."
+      dest[-pad] &= ~clockMask; // Negative index is legal & intentional
+#endif
+      dest += bitplaneSize; // Advance one scanline in dest buffer
+    }                       // end plane
+  }                         // end row
+}
+
+// Corresponding function for word output -- either 12 RGB bits (2 parallel
+// matrix chains), or 1 chain with RGB bits not in the same byte (but in the
+// same 16-bit word). Some of the comments have been stripped out since it's
+// largely the same operation, but changes are noted.
+// WORD OUTPUT IS UNTESTED AND ROW TILING MAY ESPECIALLY PRESENT ISSUES.
+void _PM_convert_565_word(Protomatter_core *core, uint16_t *source,
+                          uint16_t width) {
+  uint16_t *pinMask = (uint16_t *)core->rgbMask; // Pin bitmasks
+  uint16_t *dest = (uint16_t *)core->screenData;
+  if (core->doubleBuffer) {
+    dest += core->bufferSize / core->bytesPerElement * (1 - core->activeBuffer);
+  }
+
+  // Size of 1 plane of row pair (across full chain / tile set)
+  uint32_t bitplaneSize =
+      _PM_chunkSize * ((core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize);
+  uint8_t pad = bitplaneSize - core->chainBits; // Plane-start pad
+
+  uint32_t initialRedBit, initialGreenBit, initialBlueBit;
+  if (core->numPlanes == 6) {
+    initialRedBit = 0b1000000000000000;   // MSB red
+    initialGreenBit = 0b0000000000100000; // LSB green
+    initialBlueBit = 0b0000000000010000;  // MSB blue
+  } else {
+    uint8_t shiftLeft = 5 - core->numPlanes;
+    initialRedBit = 0b0000100000000000 << shiftLeft;
+    initialGreenBit = 0b0000000001000000 << shiftLeft;
+    initialBlueBit = 0b0000000000000001 << shiftLeft;
+  }
+
+  // Unlike the 565 byte converter, the word converter DOES clear out the
+  // matrix buffer (because each chain is OR'd into place). If a toggle
+  // register exists, "clear" really means the clock mask is set in all
+  // but the first element on a scanline (per bitplane). If no toggle
+  // register, can just zero everything out.
+#if defined(_PM_portToggleRegister)
+  // No per-chain loop is required; one clock bit handles all chains
+  uint32_t offset = 0; // Current position in the 'dest' buffer
+  uint16_t mask = core->clockMask >> (core->portOffset * 16);
+  for (uint8_t row = 0; row < core->numRowPairs; row++) {
+    for (uint8_t plane = 0; plane < core->numPlanes; plane++) {
+      dest[offset++] = 0; // First element of each plane
+      for (uint16_t x = 1; x < bitplaneSize; x++) { // All subsequent items
+        dest[offset++] = mask;
+      }
+    }
+  }
+#else
+  memset(dest, 0, core->bufferSize);
+#endif
+
+  dest += pad; // Pad value is in 'elements,' not bytes, so this is OK
+
+  for (uint8_t chain = 0; chain < core->parallel; chain++) {
+    for (uint8_t row = 0; row < core->numRowPairs; row++) {
+      uint32_t redBit = initialRedBit;
+      uint32_t greenBit = initialGreenBit;
+      uint32_t blueBit = initialBlueBit;
+      for (uint8_t plane = 0; plane < core->numPlanes; plane++) {
+#if defined(_PM_portToggleRegister)
+        // Since we're ORing in bits over an existing clock bit,
+        // prior is 0 rather than clockMask as in the byte case.
+        uint16_t prior = 0;
+#endif
+        uint16_t *d2 = dest; // Incremented per-pixel across all tiles
+
+        // Work from bottom tile to top, because data is issued in that order
+        for (int8_t tile = abs(core->tile) - 1; tile >= 0; tile--) {
+          uint16_t *upperSrc, *lowerSrc; // Canvas scanline pointers
+          int16_t srcIdx;
+          int8_t srcInc;
+
+          // Source pointer to tile's upper-left pixel
+          uint16_t *srcTileUL = source + (chain * abs(core->tile) + tile) *
+                                             width * core->numRowPairs * 2;
+          if ((tile & 1) && (core->tile < 0)) {
+            // Special handling for serpentine tiles
+            lowerSrc = srcTileUL + width * (core->numRowPairs - 1 - row);
+            upperSrc = lowerSrc + width * core->numRowPairs;
+            srcIdx = width - 1; // Work right to left
+            srcInc = -1;
+          } else {
+            // Progressive tile
+            upperSrc = srcTileUL + width * row;              // Top row
+            lowerSrc = upperSrc + width * core->numRowPairs; // Bottom row
+            srcIdx = 0;                                      // Left to right
+            srcInc = 1;
+          }
+
+          for (uint16_t x = 0; x < width; x++, srcIdx += srcInc) {
+            uint16_t upperRGB = upperSrc[srcIdx]; // Pixel in upper half
+            uint16_t lowerRGB = lowerSrc[srcIdx]; // Pixel in lower half
+            uint16_t result = 0;
+            if (upperRGB & redBit)
+              result |= pinMask[0];
+            if (upperRGB & greenBit)
+              result |= pinMask[1];
+            if (upperRGB & blueBit)
+              result |= pinMask[2];
+            if (lowerRGB & redBit)
+              result |= pinMask[3];
+            if (lowerRGB & greenBit)
+              result |= pinMask[4];
+            if (lowerRGB & blueBit)
+              result |= pinMask[5];
+              // Main difference here vs byte converter is each chain
+              // ORs new bits into place (vs single-pass overwrite).
+#if defined(_PM_portToggleRegister)
+            *d2++ |= result ^ prior; // Bitwise OR
+            prior = result;
+#else
+            *d2++ |= result; // Bitwise OR
+#endif
+          } // end x
+        }   // end tile
+        greenBit <<= 1;
+        if (plane || (core->numPlanes < 6)) {
+          redBit <<= 1;
+          blueBit <<= 1;
+        } else {
+          redBit = 0b0000100000000000;
+          blueBit = 0b0000000000000001;
+        }
+        dest += bitplaneSize; // Advance one scanline in dest buffer
+      }                       // end plane
+    }                         // end row
+    pinMask += 6;             // Next chain's RGB pin masks
+  }
+}
+
+// Corresponding function for long output -- either several parallel chains
+// (up to 5), or 1 chain with RGB bits scattered widely about the PORT.
+// Same deal, comments are pared back, see above functions for explanations.
+// LONG OUTPUT IS UNTESTED AND ROW TILING MAY ESPECIALLY PRESENT ISSUES.
+void _PM_convert_565_long(Protomatter_core *core, uint16_t *source,
+                          uint16_t width) {
+  uint32_t *pinMask = (uint32_t *)core->rgbMask; // Pin bitmasks
+  uint32_t *dest = (uint32_t *)core->screenData;
+  if (core->doubleBuffer) {
+    dest += core->bufferSize / core->bytesPerElement * (1 - core->activeBuffer);
+  }
+
+  // Size of 1 plane of row pair (across full chain / tile set)
+  uint32_t bitplaneSize =
+      _PM_chunkSize * ((core->chainBits + (_PM_chunkSize - 1)) / _PM_chunkSize);
+  uint8_t pad = bitplaneSize - core->chainBits; // Plane-start pad
+
+  uint32_t initialRedBit, initialGreenBit, initialBlueBit;
+  if (core->numPlanes == 6) {
+    initialRedBit = 0b1000000000000000;   // MSB red
+    initialGreenBit = 0b0000000000100000; // LSB green
+    initialBlueBit = 0b0000000000010000;  // MSB blue
+  } else {
+    uint8_t shiftLeft = 5 - core->numPlanes;
+    initialRedBit = 0b0000100000000000 << shiftLeft;
+    initialGreenBit = 0b0000000001000000 << shiftLeft;
+    initialBlueBit = 0b0000000000000001 << shiftLeft;
+  }
+
+#if defined(_PM_portToggleRegister)
+  // No per-chain loop is required; one clock bit handles all chains
+  uint32_t offset = 0; // Current position in the 'dest' buffer
+  for (uint8_t row = 0; row < core->numRowPairs; row++) {
+    for (uint8_t plane = 0; plane < core->numPlanes; plane++) {
+      dest[offset++] = 0; // First element of each plane
+      for (uint16_t x = 1; x < bitplaneSize; x++) { // All subsequent items
+        dest[offset++] = core->clockMask;
+      }
+    }
+  }
+#else
+  memset(dest, 0, core->bufferSize);
+#endif
+
+  dest += pad; // Pad value is in 'elements,' not bytes, so this is OK
+
+  for (uint8_t chain = 0; chain < core->parallel; chain++) {
+    for (uint8_t row = 0; row < core->numRowPairs; row++) {
+      uint32_t redBit = initialRedBit;
+      uint32_t greenBit = initialGreenBit;
+      uint32_t blueBit = initialBlueBit;
+      for (uint8_t plane = 0; plane < core->numPlanes; plane++) {
+#if defined(_PM_portToggleRegister)
+        uint32_t prior = 0;
+#endif
+        uint32_t *d2 = dest; // Incremented per-pixel across all tiles
+
+        // Work from bottom tile to top, because data is issued in that order
+        for (int8_t tile = abs(core->tile) - 1; tile >= 0; tile--) {
+          uint16_t *upperSrc, *lowerSrc; // Canvas scanline pointers
+          int16_t srcIdx;
+          int8_t srcInc;
+
+          // Source pointer to tile's upper-left pixel
+          uint16_t *srcTileUL = source + (chain * abs(core->tile) + tile) *
+                                             width * core->numRowPairs * 2;
+          if ((tile & 1) && (core->tile < 0)) {
+            // Special handling for serpentine tiles
+            lowerSrc = srcTileUL + width * (core->numRowPairs - 1 - row);
+            upperSrc = lowerSrc + width * core->numRowPairs;
+            srcIdx = width - 1; // Work right to left
+            srcInc = -1;
+          } else {
+            // Progressive tile
+            upperSrc = srcTileUL + width * row;              // Top row
+            lowerSrc = upperSrc + width * core->numRowPairs; // Bottom row
+            srcIdx = 0;                                      // Left to right
+            srcInc = 1;
+          }
+
+          for (uint16_t x = 0; x < width; x++, srcIdx += srcInc) {
+            uint16_t upperRGB = upperSrc[srcIdx]; // Pixel in upper half
+            uint16_t lowerRGB = lowerSrc[srcIdx]; // Pixel in lower half
+            uint32_t result = 0;
+            if (upperRGB & redBit)
+              result |= pinMask[0];
+            if (upperRGB & greenBit)
+              result |= pinMask[1];
+            if (upperRGB & blueBit)
+              result |= pinMask[2];
+            if (lowerRGB & redBit)
+              result |= pinMask[3];
+            if (lowerRGB & greenBit)
+              result |= pinMask[4];
+            if (lowerRGB & blueBit)
+              result |= pinMask[5];
+              // Main difference here vs byte converter is each chain
+              // ORs new bits into place (vs single-pass overwrite).
+#if defined(_PM_portToggleRegister)
+            *d2++ |= result ^ prior; // Bitwise OR
+            prior = result;
+#else
+            *d2++ |= result; // Bitwise OR
+#endif
+          } // end x
+        }   // end tile
+        greenBit <<= 1;
+        if (plane || (core->numPlanes < 6)) {
+          redBit <<= 1;
+          blueBit <<= 1;
+        } else {
+          redBit = 0b0000100000000000;
+          blueBit = 0b0000000000000001;
+        }
+        dest += bitplaneSize; // Advance one scanline in dest buffer
+      }                       // end plane
+    }                         // end row
+    pinMask += 6;             // Next chain's RGB pin masks
+  }
+}
+
+void _PM_convert_565(Protomatter_core *core, uint16_t *source, uint16_t width) {
+  // Destination address is computed in convert function
+  // (based on active buffer value, if double-buffering),
+  // just need to pass in the canvas buffer address and
+  // width in pixels.
+  if (core->bytesPerElement == 1) {
+    _PM_convert_565_byte(core, source, width);
+  } else if (core->bytesPerElement == 2) {
+    _PM_convert_565_word(core, source, width);
+  } else {
+    _PM_convert_565_long(core, source, width);
+  }
+}
+
+#endif // END ARDUINO || CIRCUITPY
+
+/* NOTES TO FUTURE SELF ----------------------------------------------------
+
+ON BYTES, WORDS and LONGS:
+I've gone back and forth between implementing all this either as it
+currently is (with byte, word and long cases for various steps), or using
+a uint32_t[64] table for expanding RGB bit combos to PORT bit combos.
+The latter would certainly simplify the code a ton, and the additional
+table lookup step wouldn't significantly impact performance, especially
+going forward with faster processors (several devices already require a
+few NOPs in the innermost loop to avoid outpacing the matrix).
+BUT, the reason this is NOT currently done is that it only allows for a
+single matrix chain (doing parallel chains would require either an
+impractically large lookup table, or adding together multiple tables'
+worth of bitmasks, which would slow things down in the vital inner loop).
+Although parallel matrix chains aren't yet 100% implemented in this code
+right now, I wanted to leave that possibility for the future, as a way to
+handle larger matrix combos, because long chains will slow down the
+refresh rate.
+*/