{"id":18626561,"url":"https://github.com/matdombrock/matrixgl","last_synced_at":"2026-04-25T21:32:16.669Z","repository":{"id":52500570,"uuid":"354504567","full_name":"matdombrock/MatrixGL","owner":"matdombrock","description":"A Microcontroller Graphics Library For LED Dot Matrix Displays","archived":false,"fork":false,"pushed_at":"2021-04-27T14:25:04.000Z","size":61,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-17T08:11:40.461Z","etag":null,"topics":["arduino","dot-matrix","graphics","led","microcontroller"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matdombrock.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-04T09:31:23.000Z","updated_at":"2025-04-10T20:25:36.000Z","dependencies_parsed_at":"2022-09-10T15:12:15.736Z","dependency_job_id":null,"html_url":"https://github.com/matdombrock/MatrixGL","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/matdombrock/MatrixGL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matdombrock%2FMatrixGL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matdombrock%2FMatrixGL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matdombrock%2FMatrixGL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matdombrock%2FMatrixGL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matdombrock","download_url":"https://codeload.github.com/matdombrock/MatrixGL/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matdombrock%2FMatrixGL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32278249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","dot-matrix","graphics","led","microcontroller"],"created_at":"2024-11-07T04:38:22.472Z","updated_at":"2026-04-25T21:32:16.644Z","avatar_url":"https://github.com/matdombrock.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MatrixGL\n\n*An Arduino Microcontroller Graphics Library For LED Dot Matrix Displays*\n\n---\n---\n\n## MD_MAX_72XX\n\nDepends on: [MD_MAX_72XX](https://github.com/MajicDesigns/MD_MAX72XX)\n\nThe MD_MAX_72XX library provides a system for addressing the \"pixels\" on the matrix individually. \n\n\u003e The library implements functions that allow the MAX72xx to be used for LED matrices (64 individual LEDs), allowing the programmer to use the LED matrix as a pixel device, displaying graphics elements much like any other pixel addressable display.\n\n\\- MAX72xx LED Matrix Display Library README\n\n*Note: The `MD_MAX_72XX` library treats additional 8x8 matrices as adding to the Y axis. This library prefers treating them as the X axis. So the axes are inverted relative to the `MD_MAX_72XX` library.*\n\n---\n---\n\n## Features\n* Frame Based Animation\n* Sprite Drawing\n* Line Drawing\n* Path Drawing\n* Character Drawing (Numbers work but letters not implemented yet)\n\nLine drawing is preformed by a custom [digital differential analyzer (DDA)](https://en.wikipedia.org/wiki/Digital_differential_analyzer_(graphics_algorithm)) implementation. \n\n## Used On\n\n### [jackmachiela/PhotoLife](https://github.com/jackmachiela/PhotoLife)\n\n\u003e This project creates an old retro-looking photo-frame with a Conway's Game of Life simulation running in it. It's designed to hang on the wall, and to work continuously without stabilising. To prevent the simulation stabilising, the frankenstein switch can be thrown to spark new life into the display - zzzap!\n\u003e \n### [matdombrock/WiFi-Clock](https://github.com/matdombrock/WIFI-Clock)\n\n\u003e A WIFI Clock + Temperature/Humidity System for ESP32 Dev Boards.\n\u003e \n\u003e Displays on a 32x8 \"pixel\" LED Matrix.\n\n## Setup\n```c++\nMatrixGL(int CLK_PIN, int DATA_PIN, int CS_PIN, int MAX_DEVICES=1, int MDX=NULL, int MDY=NULL);\n```\n\nExample:\n\n```c++\n#include \u003cMatrixGL.h\u003e\n\n#define CS_PIN 10 // The CS Pin for your device, may need changing\n#define CLK_PIN   18  // The SCK Pin for your device, may need changing\n#define DATA_PIN  23  // The MOSI Pin for your device, may need changing\n#define MAX_DEVICES 4 // How many matrix Blocks are connected?\n\nMatrixGL matrix(CLK_PIN,DATA_PIN,CS_PIN,MAX_DEVICES);\n```\n\n## Basic Usage Example\n```c++\nvoid loop(){\n  // Draw some line segments\n  matrix.delayF();// Delay based on the desired frame rate\n  matrix.clear();// Clear the display\n  matrix.drawLine(0,0,4,4);// Draw a line from 0,0 to 4,4\n  matrix.delayF();// Delay based on the desired frame rate\n  matrix.clear();// Clear the display\n  matrix.drawLine(4,4,8,8);// Draw a line from 4,4 to 8,8\n  // Draw a path\n  int points[] = {0,0, 4,4, 7,6, 8,0};// Defines the points on the path\n  matrix.lock();// Lock the display (not required)\n  matrix.clear();// Clear the display\n  matrix.drawPath(points, 8);// Draw a path from the given points\n  matrix.unlock();// Unlock the display (not required)\n}\n```\n\n## Matrix Arrangement\n\nBy default, this library assumes that any additional matrices that you include will be added to the X axis. \n\nIf desired, you can add optional arguments (MDX \u0026 MDY) to the library instantiation that allow you to define the amount of displays on your X and Y axes.\n\n*Wiring Note: You will need to wire the matrices in order from bottom left (being the first) to top right (being the last).*\n\nOnce you have it setup like that you can go ahead and start setting points that have a Y value over 7 and the library will automatically handle the addressing abstraction.\n\nSo if you had a 2x2 display setup you could draw 2 points like:\n```c++\nmatrix.drawPoint(0,0,true);\nmatrix.drawPoint(15,15,true);\n```\n\nThis will draw a point in the bottom left corner and another in the top right. The first point is drawn on the first display and the last point is drawn on last display in order of how they are wired.\n\n**NOTE: At this time, support for custom display configurations (additional matrices on the Y axis) is an experimental feature and may not play well with other features like sprite/character drawing. Please feel free to [post an issue](https://github.com/matdombrock/MatrixGL/issues/new/choose) if you encounter any.**\n\nSee [the 4x2 example](https://github.com/matdombrock/MatrixGL/blob/master/examples/4x2.ino) for more info.\n\n## Notes \u0026 Caveats\n* This library uses zero based numbering to describe coordinates.\n* Unlike many graphics libraries, this one does not start counting the Y axis from the top. So point 0,0 is the bottom left corner (as you would expect on a graphing calculator).\n* (Almost) Nothing will stop you from trying to draw outside the bounds of your matrix. Sometimes this results in overflow and sometimes wrap-around. It's up to you to avoid this.\n\n## Drawing Points\n```c++\nvoid drawPoint(int x, int y, bool on=true);\n```\nTurn on an LED at point x,y. \n\nSetting `on` to false will turn off the LED at that point.\n\n## Drawing Lines\n```c++\nvoid drawLine(int x1, int y1, int x2, int y2, bool on=true);\n```\nDraw a line from the point `x1,y1` to the point `x2,y2`.\n\nSetting `on` to false will turn off the LEDs along the line.\n\nExample:\n```c++\nmatrix.drawLine(0, 0, 6, 8);\n```\n\n## Drawing Paths\n```c++\nvoid drawPath(int points[], int pointsLen, bool on=true);\n```\nDraw a path based on the given array of point coordinates. \n\nSetting `on` to false will turn off the LEDs along the path.\n\nExample:\n```c++\nint points[] = {0,0, 4,4, 7,6, 0,0};\nmatrix.drawPath(points, 8);\n```\n\n*Note: The length of the `points` array should always be an even number. This is not currently enforced.*\n\n## Drawing Sprites\n```c++\nvoid drawSprite(bool sprite[],int w, int h, int x, int y, inverted=false);\n```\nDraw a sprite with width `w` and heigh `h` at the point `x,y`.\n\n* sprite - contains an array of boolean pixel values\n* w - The width (x length) of the sprite\n* h - The width (y length) of the sprite\n* x - The x drawing offset\n* y - The y drawing offset\n* inverted - Invert the \"pixel values\"\n\n*Note: The x and y offsets position the bottom \"left\" pixel of the sprite.\n\nExample:\n```c++\nmatrix.drawSprite(sprite1, 6,6, 0,0);\n```\n\nDefining a sprite works like this:\n```c++\nconst bool sprite[] PROGMEM = {\n  0,0,1,1,0,0,\n  0,0,1,1,0,0,\n  1,1,1,1,1,1,\n  0,1,0,0,1,0,\n  0,1,1,1,1,0,\n  0,1,0,0,1,0\n};\n```\nYou can more or less think of the sprite data as being a direct representation of the pixel matrix (assuming you lay it out in the same manner, which you don't have to). As you might have assumed, a 1 represents an active \"pixel\" (LED ON) and and a 0 represents an inactive \"pixel\" (LED OFF).\n\nDrawing a series of sprites (an animation) might look like:\n```c++\nmatrix.clear();\nmatrix.drawSprite(sprite1, 6,6, 1,1);\nmatrix.delayF();\nmatrix.clear();\nmatrix.drawSprite(sprite2, 6,6, 1,1);\nmatrix.delayF();\nmatrix.clear();\nmatrix.drawSprite(sprite3, 6,6, 1,1);\nmatrix.delayF();\n```\n\n*Also notice that the array is being stored in program memory by the use of `PROGMEM` [More Info](https://www.arduino.cc/reference/en/language/variables/utilities/progmem/). This is because sprite/frame data is much too large to store in RAM. While it would be technically possible to get away with storing a few frames/sprites of data in RAM, the `drawSprite()` method expects an array stored in program memory and will not work with an array stored in dynamic memory. Due to the fact that arrays MUST be stored in program memory, they are inherently immutable.*\n\n## Drawing Frames\n```c++\nvoid drawFrame(bool frame[], bool clearFirst, bool inverted=false)\n```\nDrawing a frame works in much the same way as drawing a sprite but we can assume that the frame will take up the entire display. Because of this we do not need to provide an x or y value and we also don't need to describe the width or height. \n\n* frame - contains an array of boolean pixel values with a length equal to the area of your display (in \"pixels\")\n* clearFirst - should the previous display buffer be cleared before drawing?\n* inverted - Invert the \"pixel values\"\n\nDefining a frame works like this:\n```c++\nconst bool frameX[256] PROGMEM = {\n0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,\n0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,\n0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,\n0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,\n0,0,1,0,0,0,0,0,0,0,1,1,0,0,0,0,0,0,0,1,0,0,0,0,0,0,1,0,0,1,1,1,\n0,1,1,1,1,0,0,0,0,1,1,1,1,0,0,0,0,0,1,1,1,0,1,0,0,1,1,1,1,1,1,1,\n1,1,1,1,1,1,0,0,1,1,1,1,1,1,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,\n1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1\n};\n```\nDrawing the frame might look like this:\n```c++\nmatrix.drawFrame(frameX,true);\n```\n\nDrawing a series of frames (an animation) might look like:\n```c++\nmatrix.drawFrame(frame1,true);\nmatrix.delayF();\nmatrix.drawFrame(frame2,true);\nmatrix.delayF();\nmatrix.drawFrame(frame3,true);\nmatrix.delayF();\n```\n\nOnce again, you can think of the frame data as being a direct representation of the pixel matrix (assuming you lay it out in the same manner). \n\nThe first value represents the \"pixel\" 0,7 (This library uses zero-based counting). The second value represents pixel 1,7 and so on. The last value represents 32,0. \n\nWhile you do not have to write out your array to match the columns and rows of your screen, the array length must be equal to the area of your display. \n\nSo, if your display is 32x8 your array MUST have a length of 256. If your display is 8x8 your array MUST have length of 16.\n\n## Drawing A Character\n```C++\nvoid drawChar(char c, int x, int y, inverted=false);\n```\n* c - Character to draw (A-\u003eZ)\n* x - X position to draw the number at\n* y - y position to draw the number at\n* inverted - Invert the \"pixel values\"\n\nYou can draw any capital (uppercase) letter between A and Z. You can also draw a colon. \n\nExample:\n```c++\ndrawChar('A', 1, 1);\n```\n\nCharacters are 4 \"pixels\" wide so if you want to space them out appropriately you should but a horizontal space of at least 5 \"pixels\" between each character. \n\nExample:\n```c++\ndrawChar('A', 1, 1);\ndrawChar('B', 6, 1);\ndrawChar('C', 11, 1);\n```\n\n## Drawing A Number\n```C++\nvoid drawNum(int n, int x, int y, inverted=false);\n```\n\n* n - Number to draw (0-\u003e9)\n* x - X position to draw the number at\n* y - y position to draw the number at\n* inverted - Invert the \"pixel values\"\n\nThis works much like drawing a sprite.  Just provide a number between 0 and 9 and tell it where to draw at. \n\n*Note: At this time all built-in number sprites are 4 \"pixels\" wide and 6 \"pixels\" high.*\n\n## Drawing A String\n```C++\nvoid drawString(String str, int length=6);\n```\n\nDraw a string on the display. The length can be greater than your actual string length.  \n\n*Note: At this time the string will be left justified. You can pad with spaces at the beginning if needed.*\n\n## Setting LED Intensity (Brightness)\n```C++\nvoid setIntensity(int intensity);\n```\n\nThe value of `intensity` should be 0 through 15.\n\n*Note: The default value is 0 (zero).*\n\n## Setting Frame Rate\n```c++\nvoid setFrameRate(int fr);\n```\n\nThe argument given for `fr` is the frame rate in 'frames per second'. \n\n## Following A Frame Rate\n```c++\nvoid delayF();\n```\nUsed to delay from some time between drawing of frames or other items. The time delayed is based on the frame rate set with `setFrameRate()`.\n\n## Delaying Several Frames\n```c++\nvoid delayN(int n);\n```\nUsed to delay for `n` frames. \n\n## Clearing The Display\n```c++\nvoid clear();\n```\nRemoves everything from the display.\n\n## Locking The Display\n```c++\nvoid lock();\n```\n\nWhen preforming a long series of draw operations you might wish to lock the display so that the updates are written to the display buffer but not displayed on the device. \n\nTo use this method effectively you need to lock the display, then clear it, write to the display, then unlock it. \n\nConsider this example:\n```c++\nvoid randomNoise(){\n  int X = matrix.lenX();\n  int Y = matrix.lenY();\n  matrix.lock();\n  matrix.clear();\n  for(int i = 0; i\u003c(X*Y); i++){\n    matrix.mx-\u003esetPoint(random(Y), random(X), true); \n  }\n  matrix.unlock();\n  matrix.delayF();\n}\n```\nWithout using the `lock()` method, you will probably have issues with the display flickering. \n\n## Unlocking The Display\n```c++\nvoid unlock();\n```\n\nUnlock the display after locking it.\n\n## Getting Display X Length\n```c++\nint lenX();\n```\n\nReturns the X length of the display\n\n## Getting Display Y Length\n```c++\nint lenY();\n```\n\nReturns the Y length of the display\n\n## Lower Level Operations\nIf you wish to access the underlying `MD_MAX72xx` library directly, you can use the pointer `mx`.\n\nExample:\n\n```c++\n#include \u003cMatrixGL.h\u003e\n\n#define CS_PIN 10\n#define MAX_DEVICES 4\n#define LENGTHX 32\n#define LENGTHY 8\n#define INTENSITY 0\n\nMatrixGL matrix(CS_PIN,MAX_DEVICES, LENGTHX, LENGTHY, INTENSITY);\n\nvoid loop(){\n  matrix.mx-\u003esetPoint(1, 1, true);\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatdombrock%2Fmatrixgl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatdombrock%2Fmatrixgl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatdombrock%2Fmatrixgl/lists"}