diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c2a26c0
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+# Our handy .gitignore for automation ease
+Doxyfile*
+doxygen_sqlite3.db
+html
diff --git a/Adafruit_Protomatter.cpp b/Adafruit_Protomatter.cpp
index e752135..2fc5d8a 100644
--- a/Adafruit_Protomatter.cpp
+++ b/Adafruit_Protomatter.cpp
@@ -1,3 +1,38 @@
+/*!
+ * @file Adafruit_Protomatter.cpp
+ *
+ * @mainpage Adafruit Protomatter RGB LED matrix library.
+ *
+ * @section intro_sec Introduction
+ *
+ * This is documentation for Adafruit's protomatter library for HUB75-style
+ * RGB LED matrices. It is designed to work with various matrices sold by
+ * Adafruit ("HUB75" is a vague term and other similar matrices are not
+ * guaranteed to work). This file is the Arduino-specific calls; the
+ * underlying C code is more platform-neutral.
+ *
+ * Adafruit invests time and resources providing this open source code,
+ * please support Adafruit and open-source hardware by purchasing products
+ * from Adafruit!
+ *
+ * @section dependencies Dependencies
+ *
+ * This library depends on
+ * Adafruit_GFX
+ * being present on your system. Please make sure you have installed the
+ * latest version before using this library.
+ *
+ * @section author Author
+ *
+ * Written by Phil "Paint Your Dragon" Burgess and Jeff Epler for
+ * Adafruit Industries, with contributions from the open source community.
+ *
+ * @section license License
+ *
+ * BSD license, all text here must be included in any redistribution.
+ *
+ */
+
// Arduino-specific wrapper for the Protomatter C library (provides
// constructor and so forth, builds on Adafruit_GFX). There should
// not be any device-specific #ifdefs here. See notes in core.c and
@@ -5,7 +40,7 @@
#include "Adafruit_Protomatter.h" // Also includes core.h & Adafruit_GFX.h
-extern Protomatter_core *_PM_protoPtr; // In core.c (via arch.h)
+extern Protomatter_core *_PM_protoPtr; ///< In core.c (via arch.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
@@ -21,13 +56,13 @@ extern Protomatter_core *_PM_protoPtr; // In core.c (via arch.h)
// 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
+#define _PM_MAX_REFRESH_HZ 250 ///< Upper limit (ish) to matrix refresh rate
// Time (in milliseconds) 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
+#define _PM_ROW_DELAY 8 ///< Delay time between row address line changes (ms)
Adafruit_Protomatter::Adafruit_Protomatter(
diff --git a/Adafruit_Protomatter.h b/Adafruit_Protomatter.h
index fea4aed..cf0ffde 100644
--- a/Adafruit_Protomatter.h
+++ b/Adafruit_Protomatter.h
@@ -7,17 +7,94 @@
#include "core.h"
#include
+/*!
+ @brief Class representing the Arduino-facing side of the Protomatter
+ library. Subclass of Adafruit_GFX's GFXcanvas16 to allow all
+ the drawing operations.
+*/
class Adafruit_Protomatter : public GFXcanvas16 {
public:
+ /*!
+ @brief Adafruit_Protomatter constructor.
+ @param bitWidth Total width of RGB matrix chain, in pixels.
+ Usu. some multiple of 32, but maybe exceptions.
+ @param bitDepth Color "depth" in bitplanes, determines range of
+ shades of red, green and blue. e.g. passing 4
+ bits = 16 shades ea. R,G,B = 16x16x16 = 4096
+ colors. Max is 6, since the GFX library works
+ with "565" RGB colors (6 bits green, 5 red/blue).
+ @param rgbCount Number of "sets" of RGB data pins, each set
+ containing 6 pins (2 ea. R,G,B). Typically 1,
+ indicating a single matrix (or matrix chain).
+ In theory (but not yet extensively tested),
+ multiple sets of pins can be driven in parallel,
+ up to 5 on some devices (if the hardware design
+ provides all those bits on one PORT).
+ @param rgbList A uint8_t array of pins (Arduino pin numbering),
+ 6X the prior rgbCount value, corresponding to
+ the 6 output color bits for a matrix (or chain).
+ Order is upper-half red, green, blue, lower-half
+ red, green blue (repeat for each add'l chain).
+ All the RGB pins (plus the clock pin below on
+ some architectures) MUST be on the same PORT
+ register. It's recommended (but not required)
+ that all RGB pins (and clock depending on arch)
+ be within the same byte of a PORT (but do not
+ need to be sequential or contiguous within that
+ byte) for more efficient RAM utilization. For
+ two concurrent chains, same principle but 16-bit
+ word instead of byte.
+ @param addrCount Number of row address lines required of matrix.
+ Total pixel height is then 2 x 2^addrCount, e.g.
+ 32-pixel-tall matrices have 4 row address lines.
+ @param addrList A uint8_t array of pins (Arduino pin numbering),
+ one per row address line.
+ @param clockPin RGB clock pin (Arduino pin #).
+ @param latchPin RGB data latch pin (Arduino pin #).
+ @param oePin Output enable pin (Arduino pin #), active low.
+ @param doubleBuffer If true, two matrix buffers are allocated,
+ so changing display contents doesn't introduce
+ artifacts mid-conversion. Requires ~2X RAM.
+ @param timer Pointer to timer peripheral or timer-related
+ struct (architecture-dependent), or NULL to
+ use a default timer ID (also arch-dependent).
+ */
Adafruit_Protomatter(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, void *timer=NULL);
~Adafruit_Protomatter(void);
+
+ /*!
+ @brief Start a Protomatter matrix display running -- initialize
+ pins, timer and interrupt into existence.
+ @return A ProtomatterStatus status, one of:
+ PROTOMATTER_OK if everything is good.
+ PROTOMATTER_ERR_PINS if data and/or clock pins are split
+ across different PORTs.
+ PROTOMATTER_ERR_MALLOC if insufficient RAM to allocate
+ display memory.
+ PROTOMATTER_ERR_ARG if a bad value was passed to the
+ constructor.
+ */
ProtomatterStatus begin(void);
- void show(void);
- uint32_t getFrameCount(void);
+
+ /*!
+ @brief Process data from GFXcanvas16 to the matrix framebuffer's
+ internal format for display.
+ */
+ void show(void);
+
+ /*!
+ @brief 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).
+ @return Frame count since previous call to function, as a uint32_t.
+ */
+ uint32_t getFrameCount(void);
private:
Protomatter_core core; // Underlying C struct
void convert_byte(uint8_t *dest); // GFXcanvas16-to-matrix
diff --git a/arch.h b/arch.h
index 1371eb6..f1a8f6a 100644
--- a/arch.h
+++ b/arch.h
@@ -1,3 +1,19 @@
+/*!
+ * @file arch.h
+ *
+ * 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.
+ *
+ */
+
// Establishes some very low-level things specific to each supported device.
// This should ONLY be included by core.c, nowhere else. Ever.
@@ -865,27 +881,27 @@ _PM_minMinPeriod: Mininum value for the "minPeriod" class member,
// DEFAULTS IF NOT DEFINED ABOVE -------------------------------------------
#if !defined(_PM_chunkSize)
- #define _PM_chunkSize 8
+ #define _PM_chunkSize 8 ///< Unroll data-stuffing loop to this size
#endif
#if !defined(_PM_clockHoldHigh)
- #define _PM_clockHoldHigh
+ #define _PM_clockHoldHigh ///< Extra cycles (if any) on clock HIGH signal
#endif
#if !defined(_PM_clockHoldLow)
- #define _PM_clockHoldLow
+ #define _PM_clockHoldLow ///< Extra cycles (if any) on clock LOW signal
#endif
#if !defined(_PM_minMinPeriod)
- #define _PM_minMinPeriod 100
+ #define _PM_minMinPeriod 100 ///< Minimum timer interval for least bit
#endif
#ifndef _PM_ALLOCATOR
- #define _PM_ALLOCATOR(x) (malloc((x)))
+ #define _PM_ALLOCATOR(x) (malloc((x))) ///< Memory alloc call
#endif
#ifndef _PM_FREE
- #define _PM_FREE(x) (free((x)))
+ #define _PM_FREE(x) (free((x))) ///< Memory free call
#endif
// ARDUINO SPECIFIC CODE ---------------------------------------------------
@@ -1251,7 +1267,7 @@ void _PM_swapbuffer_maybe(Protomatter_core *core) {
#endif // ARDUINO || CIRCUITPYTHON
#ifndef _PM_PORT_TYPE
-#define _PM_PORT_TYPE uint32_t
+ #define _PM_PORT_TYPE uint32_t ///< PORT register size/type
#endif
#endif // _PROTOMATTER_ARCH_H_
diff --git a/core.c b/core.c
index 821d7a6..c364088 100644
--- a/core.c
+++ b/core.c
@@ -1,3 +1,19 @@
+/*!
+ * @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.h regarding assumptions of hardware
// "common ground." If you find yourself doing an "#ifdef ARDUINO" or
@@ -32,13 +48,13 @@
// 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
+#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
+#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
@@ -56,8 +72,8 @@ 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))
-#define _PM_setReg(x) (*(volatile _PM_PORT_TYPE*)((x).setReg) = ((x).bit))
+#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.
@@ -525,13 +541,13 @@ void _PM_row_handler(Protomatter_core *core) {
_PM_clockHoldLow; \
*set_full = clock; /* Set clock high */ \
_PM_clockHoldHigh; \
- *clear_full = rgbclock; /* Clear RGB data + clock */
+ *clear_full = rgbclock; /* Clear RGB data + clock */ ///< Bitbang one set of RGB data bits to matrix
#endif
#if _PM_chunkSize == 1
#define PEW_UNROLL PEW
#elif _PM_chunkSize == 8
- #define PEW_UNROLL PEW PEW PEW PEW PEW PEW PEW PEW
+ #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
diff --git a/core.h b/core.h
index e76548d..a14de66 100644
--- a/core.h
+++ b/core.h
@@ -1,3 +1,19 @@
+/*!
+ * @file core.h
+ *
+ * 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.
+ *
+ */
+
#ifndef _PROTOMATTER_CORE_H_
#define _PROTOMATTER_CORE_H_
@@ -8,7 +24,7 @@ extern "C" {
#include
#include
-// Status type returned by some functions.
+/** Status type returned by some functions. */
typedef enum {
PROTOMATTER_OK, // Everything is hunky-dory!
PROTOMATTER_ERR_PINS, // Clock and/or data pins on different PORTs
@@ -16,86 +32,229 @@ typedef enum {
PROTOMATTER_ERR_ARG, // Bad input to function
} ProtomatterStatus;
-// Struct for matrix control lines NOT related to RGB data or clock, i.e.
-// latch, OE and address lines. RGB data and clock ("RGBC") are handled
-// differently as they have specific requirements (and might use a toggle
-// register if present). The data conversion functions need bitmasks for
-// RGB data but do NOT need the set or clear registers, so those items
-// are also declared as separate things in the core structure that follows.
+/** Struct for matrix control lines NOT related to RGB data or clock, i.e.
+ latch, OE and address lines. RGB data and clock ("RGBC") are handled
+ differently as they have specific requirements (and might use a toggle
+ register if present). The data conversion functions need bitmasks for
+ RGB data but do NOT need the set or clear registers, so those items are
+ also declared as separate things in the core structure that follows. */
typedef struct {
- volatile void *setReg; // GPIO bit set register
- volatile void *clearReg; // GPIO bit clear register
- uint32_t bit; // GPIO bitmask
- uint8_t pin; // Some identifier, e.g. Arduino pin #
+ volatile void *setReg; ///< GPIO bit set register
+ volatile void *clearReg; ///< GPIO bit clear register
+ uint32_t bit; ///< GPIO bitmask
+ uint8_t pin; ///< Some unique ID, e.g. Arduino pin #
} _PM_pin;
-// Struct with info about an RGB matrix chain and lots of state and buffer
-// details for the library. Toggle-related items in this structure MUST be
-// declared even if the device lacks GPIO bit-toggle registers (i.e. don't
-// do an ifdef check around these). All hardware-specific details (including
-// the presence or lack of toggle registers) are isolated to a single
-// file -- arch.h -- which should ONLY be included by core.c, and ifdef'ing
-// them would result in differing representations of this structure which
-// must be shared between the library and calling code. (An alternative is
-// to put any toggle-specific stuff at the end of the struct with an ifdef
-// check, but that's just dirty pool and asking for trouble.)
+/** Struct with info about an RGB matrix chain and lots of state and buffer
+ details for the library. Toggle-related items in this structure MUST be
+ declared even if the device lacks GPIO bit-toggle registers (i.e. don't
+ do an ifdef check around these). All hardware-specific details (including
+ the presence or lack of toggle registers) are isolated to a single
+ file -- arch.h -- which should ONLY be included by core.c, and ifdef'ing
+ them would result in differing representations of this structure which
+ must be shared between the library and calling code. (An alternative is
+ to put any toggle-specific stuff at the end of the struct with an ifdef
+ check, but that's just dirty pool and asking for trouble.) */
typedef struct {
- void *timer; // Arch-specific timer/counter info
- void *setReg; // RGBC bit set register (cast to use)
- void *clearReg; // RGBC bit clear register "
- void *toggleReg; // RGBC bit toggle register "
- uint8_t *rgbPins; // Array of RGB data pins (mult of 6)
- void *rgbMask; // PORT bit mask for each RGB pin
- uint32_t clockMask; // PORT bit mask for RGB clock
- uint32_t rgbAndClockMask; // PORT bit mask for RGB data + clock
- volatile void *addrPortToggle; // See singleAddrPort below
- void *screenData; // Per-bitplane RGB data for matrix
- _PM_pin latch; // RGB data latch
- _PM_pin oe; // !OE (LOW out enable)
- _PM_pin *addr; // Array of address pins
- uint32_t bufferSize; // Bytes per matrix buffer
- uint32_t bitZeroPeriod; // Bitplane 0 timer period
- uint32_t minPeriod; // Plane 0 timer period for ~250Hz
- volatile uint32_t frameCount; // For estimating refresh rate
- uint16_t width; // Matrix chain width in bits
- uint8_t bytesPerElement; // Using 8, 16 or 32 bits of PORT?
- uint8_t clockPin; // RGB clock pin identifier
- uint8_t parallel; // Number of concurrent matrix outs
- uint8_t numAddressLines; // Number of address line pins
- uint8_t portOffset; // Active 8- or 16-bit pos. in PORT
- uint8_t numPlanes; // Display bitplanes (1 to 6)
- uint8_t numRowPairs; // Addressable row pairs
- bool doubleBuffer; // 2X buffers for clean switchover
- bool singleAddrPort; // If 1, all addr lines on same PORT
- volatile uint8_t activeBuffer; // Index of currently-displayed buf
- volatile uint8_t plane; // Current bitplane (changes in ISR)
- volatile uint8_t row; // Current scanline (changes in ISR)
- volatile uint8_t prevRow; // Scanline from prior ISR
- volatile bool swapBuffers; // If 1, awaiting double-buf switch
+ void *timer; ///< Arch-specific timer/counter info
+ void *setReg; ///< RGBC bit set register (cast to use)
+ void *clearReg; ///< RGBC bit clear register "
+ void *toggleReg; ///< RGBC bit toggle register "
+ uint8_t *rgbPins; ///< Array of RGB data pins (mult of 6)
+ void *rgbMask; ///< PORT bit mask for each RGB pin
+ uint32_t clockMask; ///< PORT bit mask for RGB clock
+ uint32_t rgbAndClockMask; ///< PORT bit mask for RGB data + clock
+ volatile void *addrPortToggle; ///< See singleAddrPort below
+ void *screenData; ///< Per-bitplane RGB data for matrix
+ _PM_pin latch; ///< RGB data latch
+ _PM_pin oe; ///< !OE (LOW out enable)
+ _PM_pin *addr; ///< Array of address pins
+ uint32_t bufferSize; ///< Bytes per matrix buffer
+ uint32_t bitZeroPeriod; ///< Bitplane 0 timer period
+ uint32_t minPeriod; ///< Plane 0 timer period for ~250Hz
+ volatile uint32_t frameCount; ///< For estimating refresh rate
+ uint16_t width; ///< Matrix chain width in bits
+ uint8_t bytesPerElement; ///< Using 8, 16 or 32 bits of PORT?
+ uint8_t clockPin; ///< RGB clock pin identifier
+ uint8_t parallel; ///< Number of concurrent matrix outs
+ uint8_t numAddressLines; ///< Number of address line pins
+ uint8_t portOffset; ///< Active 8- or 16-bit pos. in PORT
+ uint8_t numPlanes; ///< Display bitplanes (1 to 6)
+ uint8_t numRowPairs; ///< Addressable row pairs
+ bool doubleBuffer; ///< 2X buffers for clean switchover
+ bool singleAddrPort; ///< If 1, all addr lines on same PORT
+ volatile uint8_t activeBuffer; ///< Index of currently-displayed buf
+ volatile uint8_t plane; ///< Current bitplane (changes in ISR)
+ volatile uint8_t row; ///< Current scanline (changes in ISR)
+ volatile uint8_t prevRow; ///< Scanline from prior ISR
+ volatile bool swapBuffers; ///< If 1, awaiting double-buf switch
} Protomatter_core;
// Protomatter core function prototypes. Environment-specific code (like the
// Adafruit_Protomatter class for Arduino) calls on these underlying things,
// and has to provide a few extras of its own (interrupt handlers and such).
// User code shouldn't need to invoke any of them directly.
+
+/*!
+ @brief Initialize values in Protomatter_core structure.
+ @param core Pointer to Protomatter_core structure.
+ @param bitWidth Total width of RGB matrix chain, in pixels.
+ Usu. some multiple of 32, but maybe exceptions.
+ @param bitDepth Color "depth" in bitplanes, determines range of
+ shades of red, green and blue. e.g. passing 4
+ bits = 16 shades ea. R,G,B = 16x16x16 = 4096
+ colors.
+ @param rgbCount Number of "sets" of RGB data pins, each set
+ containing 6 pins (2 ea. R,G,B). Typically 1,
+ indicating a single matrix (or matrix chain).
+ In theory (but not yet extensively tested),
+ multiple sets of pins can be driven in parallel,
+ up to 5 on some devices (if the hardware design
+ provides all those bits on one PORT).
+ @param rgbList A uint8_t array of pins (values are platform-
+ dependent), 6X the prior rgbCount value,
+ corresponding to the 6 output color bits for a
+ matrix (or chain). Order is upper-half red, green,
+ blue, lower-half red, green blue (repeat for each
+ add'l chain). All the RGB pins (plus the clock pin
+ below on some architectures) MUST be on the same
+ PORT register. It's recommended (but not required)
+ that all RGB pins (and clock depending on arch) be
+ within the same byte of a PORT (but do not need to
+ be sequential or contiguous within that byte) for
+ more efficient RAM utilization. For two concurrent
+ chains, same principle but 16-bit word.
+ @param addrCount Number of row address lines required of matrix.
+ Total pixel height is then 2 x 2^addrCount, e.g.
+ 32-pixel-tall matrices have 4 row address lines.
+ @param addrList A uint8_t array of pins (platform-dependent pin
+ numbering), one per row address line.
+ @param clockPin RGB clock pin (platform-dependent pin #).
+ @param latchPin RGB data latch pin (platform-dependent pin #).
+ @param oePin Output enable pin (platform-dependent pin #),
+ active low.
+ @param doubleBuffer If true, two matrix buffers are allocated,
+ so changing display contents doesn't introduce
+ artifacts mid-conversion. Requires ~2X RAM.
+ @param timer Pointer to timer peripheral or timer-related
+ struct (architecture-dependent), or NULL to
+ use a default timer ID (also arch-dependent).
+ @return A ProtomatterStatus status, one of:
+ PROTOMATTER_OK if everything is good.
+ PROTOMATTER_ERR_PINS if data and/or clock pins are split across
+ different PORTs.
+ PROTOMATTER_ERR_MALLOC if insufficient RAM to allocate display
+ memory.
+ PROTOMATTER_ERR_ARG if a bad value (core or timer pointer) was
+ passed in.
+*/
extern 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, void *timer);
+
+/*!
+ @brief Allocate display buffers and populate additional elements of a
+ Protomatter matrix.
+ @param core Pointer to Protomatter_core structure.
+ @return A ProtomatterStatus status, one of:
+ PROTOMATTER_OK if everything is good.
+ PROTOMATTER_ERR_PINS if data and/or clock pins are split across
+ different PORTs.
+ PROTOMATTER_ERR_MALLOC if insufficient RAM to allocate display
+ memory.
+ PROTOMATTER_ERR_ARG if a bad value.
+*/
extern ProtomatterStatus _PM_begin(Protomatter_core *core);
-extern void _PM_stop(Protomatter_core *core);
-extern void _PM_resume(Protomatter_core *core);
-extern void _PM_free(Protomatter_core *core);
-extern void _PM_row_handler(Protomatter_core *core);
-extern uint32_t _PM_getFrameCount(Protomatter_core *core);
-extern void _PM_timerStart(void *tptr, uint32_t period);
-extern uint32_t _PM_timerStop(void *tptr);
-extern uint32_t _PM_timerGetCount(void *tptr);
-extern void _PM_convert_565(Protomatter_core *core,
+
+/*!
+ @brief 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.
+ @param core Pointer to Protomatter_core structure.
+*/
+extern void _PM_stop(Protomatter_core *core);
+
+/*!
+ @brief Start or restart a matrix. Initialize counters, configure and
+ start timer.
+ @param core Pointer to Protomatter_core structure.
+*/
+extern void _PM_resume(Protomatter_core *core);
+
+/*!
+ @brief Deallocate memory associated with Protomatter_core structure
+ (e.g. screen data, pin lists for data and rows). Does not
+ deallocate the structure itself.
+ @param core Pointer to Protomatter_core structure.
+*/
+extern void _PM_free(Protomatter_core *core);
+
+/*!
+ @brief Matrix "row handler" that's called by the timer interrupt.
+ Handles row address lines and issuing data to matrix.
+ @param core Pointer to Protomatter_core structure.
+*/
+extern void _PM_row_handler(Protomatter_core *core);
+
+/*!
+ @brief 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).
+ @param core Pointer to Protomatter_core structure.
+ @return Frame count since previous call to function, as a uint32_t.
+*/
+extern uint32_t _PM_getFrameCount(Protomatter_core *core);
+
+/*!
+ @brief Start (or restart) a timer/counter peripheral.
+ @param tptr Pointer to timer/counter peripheral OR a struct
+ encapsulating information about a timer/counter
+ periph (architecture-dependent).
+ @param period Timer 'top' / rollover value.
+*/
+extern void _PM_timerStart(void *tptr, uint32_t period);
+
+/*!
+ @brief Stop timer/counter peripheral.
+ @param tptr Pointer to timer/counter peripheral OR a struct
+ encapsulating information about a timer/counter
+ periph (architecture-dependent).
+ @return Counter value when timer was stopped.
+*/
+extern uint32_t _PM_timerStop(void *tptr);
+
+/*!
+ @brief Query a timer/counter peripheral's current count.
+ @param tptr Pointer to timer/counter peripheral OR a struct
+ encapsulating information about a timer/counter
+ periph (architecture-dependent).
+ @return Counter value.
+*/
+extern uint32_t _PM_timerGetCount(void *tptr);
+
+/*!
+ @brief Converts image data from GFX16 canvas to the matrices weird
+ internal format.
+ @param core Pointer to Protomatter_core structure.
+ @param source Pointer to source image data (see Adafruit_GFX 16-bit
+ canvas type for format).
+ @param width Width of canvas in pixels, as this may be different than
+ the matrix pixel width due to row padding.
+*/
+extern void _PM_convert_565(Protomatter_core *core,
uint16_t *source, uint16_t width);
-extern void _PM_swapbuffer_maybe(Protomatter_core *core);
+
+/*!
+ @brief Pauses until the next vertical blank to avoid 'tearing' animation
+ (if display is double-buffered). If single-buffered, has no effect.
+ @param core Pointer to Protomatter_core structure.
+*/
+extern void _PM_swapbuffer_maybe(Protomatter_core *core);
#ifdef __cplusplus
} // extern "C"
diff --git a/library.properties b/library.properties
index 2f5d476..109bc50 100644
--- a/library.properties
+++ b/library.properties
@@ -6,5 +6,5 @@ sentence=This is a library for the Adafruit RGB LED matrix.
paragraph=RGB LED matrix.
category=Display
url=https://github.com/adafruit/Adafruit_protomatter
-architectures=*
+architectures=samd,nrf52,stm32
depends=Adafruit GFX Library