|
MaxMatrix
Drive chained 8x8 LED dot matrix modules with MAX7219.
|
The matrix a sketch draws on: a chain of 8x8 modules, in the coordinates the viewer sees. More...
#include <MaxMatrix.h>
Public Member Functions | |
| Matrix (uint8_t data_in_pin, uint8_t chip_select_pin, uint8_t clock_pin, span< Byte > buffer) | |
| Makes a matrix on the chain at these pins, in the buffer given, and empties it. | |
| ~Matrix ()=default | |
| Leaves the LEDs as they are. | |
| Matrix (Matrix const &)=delete | |
| Not copyable: the copy would draw into the same buffer. | |
| Matrix & | operator= (Matrix const &)=delete |
| Not assignable, as it is not copyable. | |
| MAXMATRIX_NODISCARD uint8_t | GetNumberOfModules () const |
| Returns the modules of the chain. | |
| MAXMATRIX_NODISCARD uint8_t | GetNumberOfColumns () const |
| Returns the columns of the matrix, eight per module. | |
| MAXMATRIX_NODISCARD State | GetState () const |
| Returns what the matrix is doing; State::kReady once a shifted text is complete. | |
| MAXMATRIX_NODISCARD bool | GetAutoUpdate () const |
| Returns whether every function that draws sends its result at once; see SetAutoUpdate(). | |
| MAXMATRIX_NODISCARD uint16_t | GetShiftInterval () const |
| Returns the milliseconds per column of a shifting text; see SetShiftInterval(). | |
| MAXMATRIX_NODISCARD uint8_t | GetDataInPin () const |
| Returns the pin DIN of the chain is connected to. | |
| MAXMATRIX_NODISCARD uint8_t | GetChipSelectPin () const |
| Returns the pin CS of the chain is connected to. | |
| MAXMATRIX_NODISCARD uint8_t | GetClockPin () const |
| Returns the pin CLK of the chain is connected to. | |
| MAXMATRIX_NODISCARD ModuleType | GetModuleType () const |
| Returns how the LEDs of every module are wired; see SetModuleType(). | |
| MAXMATRIX_NODISCARD MatrixOrientation | GetMatrixOrientation () const |
| Returns how the whole matrix is turned; see SetMatrixOrientation(). | |
| MAXMATRIX_NODISCARD uint8_t | GetSpaceBetweenChars () const |
| Returns the empty columns between two chars of a text. | |
| MAXMATRIX_NODISCARD Result< Byte > | GetColumn (int16_t column) |
| Returns a column of the matrix. | |
| MAXMATRIX_NODISCARD Result< Byte > | GetColumn (uint8_t module, uint8_t column) |
| Returns a column of a module. | |
| MAXMATRIX_NODISCARD Status | GetRow (int16_t row, span< Byte > values) |
| Gives a row of the matrix, one byte per module. | |
| MAXMATRIX_NODISCARD Result< Byte > | GetRow (uint8_t module, uint8_t row) |
| Returns a row of a module. | |
| MAXMATRIX_NODISCARD Result< bool > | GetDot (int16_t column, int16_t row) |
| Returns whether a dot is lit. | |
| MAXMATRIX_NODISCARD span< uint8_t const > | GetFont () const |
| Returns the font every char is drawn in. | |
| void | SetDataInPin (uint8_t data_in_pin) |
| Sets the pin DIN of the chain is connected to. | |
| void | SetChipSelectPin (uint8_t chip_select_pin) |
| Sets the pin CS of the chain is connected to. | |
| void | SetClockPin (uint8_t clock_pin) |
| Sets the pin CLK of the chain is connected to. | |
| void | SetAutoUpdate (bool auto_update) |
| Sets whether what is drawn is sent at once. | |
| void | SetShiftInterval (uint16_t shift_interval) |
| Sets the milliseconds per column of a shifting text. | |
| Status | SetIntensity (uint8_t intensity) |
| Sets how bright every LED is lit. | |
| void | SetShutdown (bool shutdown) |
| Turns the LEDs of every MAX7219 off, or on again. | |
| void | SetDisplayTest (bool display_test) |
| Lights every LED at full brightness, or shows the picture again. | |
| void | SetColumn (int16_t column, Byte value) |
| Sets a column of the matrix. | |
| void | SetColumn (uint8_t module, uint8_t column, Byte value) |
| Sets a column of a module. | |
| void | SetRow (int16_t row, span< Byte const > values) |
| Sets a row of the matrix, one byte per module. | |
| void | SetRow (uint8_t module, uint8_t row, Byte value) |
| Sets a row of a module. | |
| void | SetDot (int16_t column, int16_t row, bool value) |
| Lights a dot or turns it off. | |
| void | DrawLine (int16_t x0, int16_t y0, int16_t x1, int16_t y1, bool value) |
| Draws a straight line from one dot to another, both ends included. | |
| void | DrawRect (int16_t x, int16_t y, int16_t width, int16_t height, bool value) |
| Draws the outline of a rectangle. | |
| void | FillRect (int16_t x, int16_t y, int16_t width, int16_t height, bool value) |
| Draws a rectangle with its inside. | |
| void | DrawCircle (int16_t x, int16_t y, int16_t radius, bool value) |
| Draws the outline of a circle. | |
| void | DrawBitmap (int16_t x, int16_t y, span< uint8_t const > bitmap) |
| Draws a picture from flash, 8 rows high, with its top left corner at x, y. | |
| void | DrawBitmap (int16_t x, int16_t y, uint8_t height, span< uint8_t const > bitmap) |
| Draws a picture from flash with its top left corner at x, y. | |
| Status | SetChar (int16_t x, int16_t y, char c) |
| Draws a char with its top left corner at x, y. | |
| Status | SetCharWithShift (char c) |
| Starts shifting a char in from the right, until it stands at the right edge. | |
| Status | SetText (span< char const > text) |
| Draws a text from the left edge, as far as it fits. | |
| Status | SetTextWithShift (span< char const > text, bool repeat=false) |
| Starts shifting a text in from the right, until its last char stands at the right edge, or over and over. | |
| void | StopShift () |
| Stops a shifting text or char where it is. | |
| void | SetSpaceBetweenChars (uint8_t space_between_chars) |
| Sets the empty columns between two chars of a text. | |
| Status | SetFont (span< uint8_t const > font) |
| Sets the font every char is drawn in from now on. | |
| void | SetSprite (int16_t x, int16_t y, Sprite const &sprite) |
| Draws a sprite with its top left corner at x, y. | |
| void | SetModuleType (ModuleType module_type) |
| Sets how the LEDs of every module are wired. | |
| void | SetMatrixOrientation (MatrixOrientation matrix_orientation) |
| Sets how the whole matrix is turned. | |
| void | Init () |
| Sets the chain up: the pins, every register of every MAX7219, and every LED off. | |
| void | ShiftTask () |
| Shifts a text or a char one column further, if the shift interval has passed. | |
| void | Update () |
| Sends what was drawn since the last update. | |
| void | Clear () |
| Turns every LED off. | |
| void | RegisterWrite (uint8_t register_address, uint8_t register_value) |
| Writes one register of every MAX7219 in the chain, at once. | |
| void | ShiftLeft (ShiftFill fill=ShiftFill::kZero) |
| Shifts the whole picture one column to the left. | |
| Byte | ShiftLeft (Byte shifted_in) |
| Shifts the whole picture one column to the left, with a column of the sketch coming in at the right. | |
| void | ShiftRight (ShiftFill fill=ShiftFill::kZero) |
| Shifts the whole picture one column to the right. | |
| Byte | ShiftRight (Byte shifted_in) |
| Shifts the whole picture one column to the right, with a column of the sketch coming in at the left. | |
| void | ShiftUp (ShiftFill fill=ShiftFill::kZero) |
| Shifts the whole picture one row up. | |
| void | ShiftDown (ShiftFill fill=ShiftFill::kZero) |
| Shifts the whole picture one row down. | |
The matrix a sketch draws on: a chain of 8x8 modules, in the coordinates the viewer sees.
Every function that draws changes the buffer and, with auto update on, the default, sends what changed before it returns: one frame per changed column of a module, eight at most, however much the call drew. A sketch that builds one picture out of many calls holds the sending back with a Batch, or with SetAutoUpdate() and Update(), so that no half of a picture is ever shown. The intensity and the other registers are sent at once either way: they are not part of the picture.
A sketch makes it as a MatrixOf, which brings the buffer for its chain:
A shifting text keeps its own pace: ShiftTask() may be called on every loop() and takes a step only when the shift interval has passed since the last one, so that no sketch has to time it.
| max_matrix::Matrix::Matrix | ( | uint8_t | data_in_pin, |
| uint8_t | chip_select_pin, | ||
| uint8_t | clock_pin, | ||
| span< Byte > | buffer ) |
Makes a matrix on the chain at these pins, in the buffer given, and empties it.
Nothing is sent until Init(). MatrixOf brings the buffer itself and checks the number of modules when the sketch is compiled; this is for a chain whose length is known only at run time, or a buffer that lies elsewhere. The length of the buffer says how many modules the chain has.
| [in] | data_in_pin | The pin DIN of the chain is connected to. |
| [in] | chip_select_pin | The pin CS of the chain is connected to. |
| [in] | clock_pin | The pin CLK of the chain is connected to. |
| [out] | buffer | The buffer, BufferSize() of the modules in the chain, 1 to kMaxNumberOfModules; it has to live as long as the matrix. |
|
inline |
Draws a picture from flash, 8 rows high, with its top left corner at x, y.
The picture is a column per byte, bit 0 the top row, as a glyph of a font: a 0 bit turns its dot off. What lies off the matrix is left out.
| [in] | x | The column of the left edge; it may lie off the matrix. |
| [in] | y | The row of the top edge; it may lie off the matrix. |
| [in] | bitmap | The columns, in PROGMEM; as many as it holds. |
|
inline |
Draws a picture from flash with its top left corner at x, y.
The picture is a column per byte, bit 0 the top row, as a glyph of a font: a 0 bit turns its dot off. Rows below height are left as they are, and what lies off the panel is left out.
The height goes before the bitmap, so that a width after it, as the columns were once given, does not compile: the bitmap brings its width.
| [in] | x | The column of the left edge; it may lie off the panel. |
| [in] | y | The row of the top edge; it may lie off the panel. |
| [in] | height | The rows of the picture, 1 to 8. |
| [in] | bitmap | The columns, in PROGMEM; as many as it holds. |
|
inline |
Draws the outline of a circle.
What lies off the panel is left out, as for SetDot(). A radius of 0 draws the centre only, a negative one nothing.
| [in] | x | The column of the centre. |
| [in] | y | The row of the centre. |
| [in] | radius | The dots from the centre to the outline; 3 fills the height of the panel. |
| [in] | value | True to light the outline, false to turn it off. |
|
inline |
Draws a straight line from one dot to another, both ends included.
What lies off the panel is left out, as for SetDot(); the ends may lie off it.
| [in] | x0 | The column of the first end. |
| [in] | y0 | The row of the first end. |
| [in] | x1 | The column of the second end. |
| [in] | y1 | The row of the second end. |
| [in] | value | True to light the line, false to turn it off. |
|
inline |
Draws the outline of a rectangle.
What lies off the panel is left out, as for SetDot(). A width or height of 0 or less draws nothing.
| [in] | x | The column of the left edge. |
| [in] | y | The row of the top edge. |
| [in] | width | The columns it spans. |
| [in] | height | The rows it spans. |
| [in] | value | True to light the outline, false to turn it off. |
|
inline |
Draws a rectangle with its inside.
What lies off the panel is left out, as for SetDot(). A width or height of 0 or less draws nothing.
| [in] | x | The column of the left edge. |
| [in] | y | The row of the top edge. |
| [in] | width | The columns it spans. |
| [in] | height | The rows it spans. |
| [in] | value | True to light it, false to turn it off. |
|
inline |
Returns a column of the matrix.
| [in] | column | The column, from 0 at the left to eight times the modules. |
|
inline |
Returns a column of a module.
| [in] | module | The module, from 0 at the left. |
| [in] | column | The column within the module, 0 to 7. |
|
inline |
Returns whether a dot is lit.
| [in] | column | The column, negative to the left of the panel. |
| [in] | row | The row, negative above the panel. |
|
inline |
Returns the font every char is drawn in.
|
inline |
Gives a row of the matrix, one byte per module.
| [in] | row | The row, from 0 at the top. |
| [out] | values | The row, bit 7 of each byte the leftmost column of its module; left as it was on an error. |
|
inline |
Returns a row of a module.
The leftmost column is in bit 7, so that a row written as a binary literal looks like the dots it stands for.
| [in] | module | The module, from 0 at the left. |
| [in] | row | The row within the module, 0 to 7. |
| void max_matrix::Matrix::Init | ( | ) |
Sets the chain up: the pins, every register of every MAX7219, and every LED off.
The intensity is set to its start value. The cleared matrix is sent even with auto update off, as after power-up the LEDs show anything.
|
inline |
Writes one register of every MAX7219 in the chain, at once.
| [in] | register_address | The address of the register, one of the MAX7219_REG_..._ADDRESS. |
| [in] | register_value | The value for every module. |
| void max_matrix::Matrix::SetAutoUpdate | ( | bool | auto_update | ) |
Sets whether what is drawn is sent at once.
On, the default, every function that draws sends its result before it returns. Off, only Update() sends. Turning it on sends what was drawn while it was off. A Batch turns it off for a block and back on at its end.
| [in] | auto_update | True to send after every function that draws. |
|
inline |
Draws a char with its top left corner at x, y.
What lies off the matrix is left out.
| [in] | x | The column of the left edge; it may lie off the matrix. |
| [in] | y | The row of the top edge; it may lie off the matrix. |
| [in] | c | The char, latin-1. |
| Status max_matrix::Matrix::SetCharWithShift | ( | char | c | ) |
Starts shifting a char in from the right, until it stands at the right edge.
ShiftTask() takes the steps; GetState() is State::kCharShift until the char stands.
| [in] | c | The char, latin-1. |
|
inline |
Sets the pin CS of the chain is connected to.
| [in] | chip_select_pin | The pin; Init() makes it an output. |
|
inline |
Sets the pin CLK of the chain is connected to.
| [in] | clock_pin | The pin; Init() makes it an output. |
|
inline |
Sets a column of the matrix.
A column off the panel is left out, as for SetDot().
| [in] | column | The column, from 0 at the left to eight times the modules. |
| [in] | value | The column, bit 0 the top row. |
|
inline |
Sets a column of a module.
A module or a column that does not exist is left out.
| [in] | module | The module, from 0 at the left. |
| [in] | column | The column within the module, 0 to 7. |
| [in] | value | The column, bit 0 the top row. |
|
inline |
Sets the pin DIN of the chain is connected to.
| [in] | data_in_pin | The pin; Init() makes it an output. |
| void max_matrix::Matrix::SetDisplayTest | ( | bool | display_test | ) |
Lights every LED at full brightness, or shows the picture again.
The display test of the MAX7219 overrides the picture and the intensity without changing either, and also lights a module in shutdown: a check that every LED and every module of the chain works. Sent at once, whatever auto update is.
| [in] | display_test | True to light every LED, false to show the picture again. |
|
inline |
Lights a dot or turns it off.
A dot off the panel is left out rather than reported: a sprite, a line or a text that lies partly off the panel is drawn all the time while something moves in or out, and a sketch would only have to clip it itself. Adafruit GFX's drawPixel() and Rust's embedded-graphics do the same.
| [in] | column | The column, negative to the left of the panel. |
| [in] | row | The row, negative above the panel. |
| [in] | value | True to light it. |
Sets the font every char is drawn in from now on.
A font of MD_MAX72XX serves with its bytes as they are, in make_array() rather than its C array; Font describes the format. Chars drawn already stay as they are, and a char that shifts in goes on in the font it started in. kDefaultFont is the font MaxMatrix starts with.
The length of the font is that of its array, which the span takes from it, so that the whole font is checked once, here, and no char can be read past its end. A font known only by its address, as one of a table of fonts, is passed with its length, {font, size}. A font in RAM, without PROGMEM, fails as well, almost always, as the Uno reads it from flash.
| [in] | font | The font, in flash; it has to live as long as it is set, as a PROGMEM array does. |
| Status max_matrix::Matrix::SetIntensity | ( | uint8_t | intensity | ) |
Sets how bright every LED is lit.
Sent at once, whatever auto update is.
| [in] | intensity | The intensity, 0 to 15. |
|
inline |
Sets how the whole matrix is turned.
By 180 degrees for a board mounted upside down, with the module at the input then on the left; in addition to the module type. The picture stays as the viewer sees it; the buffer is turned along.
| [in] | matrix_orientation | 0 or 180 degrees. |
|
inline |
Sets how the LEDs of every module are wired.
The picture stays as the viewer sees it; the buffer is rewritten along.
| [in] | module_type | The type of the modules, as MD_MAX72XX names it. |
Sets a row of the matrix, one byte per module.
A row off the panel is left out, as for SetDot(), and so are the modules beyond the bytes given, or the bytes beyond the modules.
| [in] | row | The row, from 0 at the top. |
| [in] | values | The row, bit 7 of each byte the leftmost column of its module. |
|
inline |
Sets a row of a module.
A module or a row that does not exist is left out.
| [in] | module | The module, from 0 at the left. |
| [in] | row | The row within the module, 0 to 7. |
| [in] | value | The row, bit 7 the leftmost column. |
|
inline |
Sets the milliseconds per column of a shifting text.
| [in] | shift_interval | The milliseconds; 0 makes every ShiftTask() a step. |
| void max_matrix::Matrix::SetShutdown | ( | bool | shutdown | ) |
Turns the LEDs of every MAX7219 off, or on again.
In shutdown the MAX7219s draw next to no current, keep their registers and still take what is drawn: the LEDs show the picture as it is then once the shutdown ends, at the intensity they had. Sent at once, whatever auto update is.
| [in] | shutdown | True to turn the LEDs off, false to turn them on again. |
|
inline |
Sets the empty columns between two chars of a text.
| [in] | space_between_chars | The number of empty columns. |
|
inline |
Draws a sprite with its top left corner at x, y.
What lies off the matrix is left out.
| [in] | x | The column of the left edge; it may lie off the matrix. |
| [in] | y | The row of the top edge; it may lie off the matrix. |
| [in] | sprite | The sprite. |
Draws a text from the left edge, as far as it fits.
A text in quotes or a char array passes as it is; a text known only by a pointer is passed with its length, {text, strlen(text)}.
| [in] | text | The text, UTF-8 or latin-1, up to its terminating null character or the end of the span, whichever comes first. |
Starts shifting a text in from the right, until its last char stands at the right edge, or over and over.
ShiftTask() takes the steps; GetState() is State::kStringShift until the text stands. A text that repeats goes on with its first char right after its last, so a few spaces at its end keep the two apart; it shifts until StopShift() or the next shift starts.
| [in] | text | The text, UTF-8 or latin-1, up to its terminating null character or the end of the span, as for SetText(). It has to live until the text stands, or as long as it repeats. |
| [in] | repeat | True to start over after the last char, without end. |
|
inline |
Shifts the whole picture one row down.
| [in] | fill | What comes in at the top: an empty row, the bottom one, or the top one as it was. |
Shifts the whole picture one column to the left, with a column of the sketch coming in at the right.
A sketch that feeds a column on every step gets a band of any length, from flash, a sensor or a calculation, and what falls out at the left, to keep or pass on.
| [in] | shifted_in | The column that comes in, bit 0 the top row. |
|
inline |
Shifts the whole picture one column to the left.
| [in] | fill | What comes in at the right: an empty column, the leftmost one, or the rightmost one as it was. |
Shifts the whole picture one column to the right, with a column of the sketch coming in at the left.
| [in] | shifted_in | The column that comes in, bit 0 the top row. |
|
inline |
Shifts the whole picture one column to the right.
| [in] | fill | What comes in at the left: an empty column, the rightmost one, or the leftmost one as it was. |
| void max_matrix::Matrix::ShiftTask | ( | ) |
Shifts a text or a char one column further, if the shift interval has passed.
Call it on every loop() until GetState() is State::kReady again. It takes a step only when the shift interval has passed since the last one, and with an interval of 0 on every call. A call that comes late takes one step, not the ones it missed: catching up would make the text jump after loop() was held up.
|
inline |
Shifts the whole picture one row up.
| [in] | fill | What comes in at the bottom: an empty row, the top one, or the bottom one as it was. |
| void max_matrix::Matrix::StopShift | ( | ) |
Stops a shifting text or char where it is.
The picture stays as it is, and GetState() is State::kReady; ShiftTask() takes no step until the next shift starts. Without a shift, it does nothing.
|
inline |
Sends what was drawn since the last update.
Only needed with auto update off; see Batch.