/*! * @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. * */ #pragma once #ifdef __cplusplus extern "C" { #endif #include #include /** 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 PROTOMATTER_ERR_MALLOC, // Couldn't allocate memory for display 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. */ 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 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.) */ 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 only in bits uint16_t chainBits; ///< Matrix chain width*tiling 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 int8_t tile; ///< Vertical tiling repetitions 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 tile If multiple matrices are chained and stacked vertically (rather than or in addition to horizontally), the number of vertical tiles is specified here. Positive values indicate a "progressive" arrangement (always left-to-right), negative for a "serpentine" arrangement (alternating 180 degree orientation). Horizontal tiles are implied in the 'bitWidth' argument. @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, int8_t tile, 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); /*! @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_deallocate(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 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); #if defined(ARDUINO) || defined(CIRCUITPY) /*! @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); #endif // END ARDUINO || CIRCUITPY #ifdef __cplusplus } // extern "C" #endif