Draw a PNG from a memory buffer
What this example shows
Reading a whole PNG file from the microSD card into a RAM buffer and drawing it from there with drawPngFromBuffer(). The same approach works for PNG data that comes from another source, such as the network.
Example code
Trimmed from the pinned example: only the file header comment is removed, the code is unchanged.
#if !defined(ARDUINO_INKPLATE10) && !defined(ARDUINO_INKPLATE10V2)
#error "Wrong board selection for this example, please select e-radionica Inkplate10 or Soldered Inkplate10 in the boards menu."
#endif
#include "Inkplate.h"
Inkplate display(INKPLATE_3BIT);
void setup()
{
display.begin();
display.clearDisplay();
display.setTextColor(BLACK);
display.setTextSize(2);
if (!display.sdCardInit())
{
display.println("SD card error!");
display.display();
return;
}
SdFile file;
if (!file.open("image.png", O_RDONLY))
{
display.println("Cannot open image.png");
display.display();
display.sdCardSleep();
return;
}
uint32_t fileSize = file.fileSize();
// Allocate a buffer large enough for the whole file
uint8_t *buf = (uint8_t *)malloc(fileSize);
if (!buf)
{
display.println("Not enough RAM for image buffer!");
display.display();
file.close();
display.sdCardSleep();
return;
}
// Read the entire file into the buffer
file.read(buf, fileSize);
file.close();
display.sdCardSleep();
// Draw the PNG from the in-memory buffer
if (!display.image.drawPngFromBuffer(buf, fileSize, 0, 0, true, false))
{
display.println("PNG decode error");
}
free(buf);
display.display();
}
void loop()
{
// Nothing...
}
Functions used
Inkplate(uint8_t mode)returns NoneCreates the display object. `INKPLATE_1BIT` is black and white and supports partial updates. `INKPLATE_3BIT` gives 8 levels of grey but only full updates.
ReturnsConstructor; no return value.
Parameters
| Type | Name | Description |
|---|---|---|
uint8_t | mode | INKPLATE_1BIT or INKPLATE_3BIT. |
display.begin()returns voidInitializes the library and the display. Call it once, at the start of `setup()`.
ReturnsNothing.
display.clearDisplay()returns voidClears the frame buffer in memory. It does not change what the panel shows until you call `display()`.
ReturnsNothing.
display.setTextColor(uint16_t c)returns voidSets the text color.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
uint16_t | c | Text color, for example BLACK. |
display.setTextSize(uint8_t s)returns voidScales text by an integer factor. The base font is 5 x 7 pixels.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
uint8_t | s | Scale factor. |
display.sdCardInit()returns int16_tPowers the microSD card and starts the SD interface.
Returns`1` if the card initialized, `0` if it failed.
display.println(value)returns size_tSame as `print()`, then moves the cursor to the start of the next line. It comes from the Arduino `Print` class that `Adafruit_GFX` builds on.
ReturnsNumber of bytes printed.
Parameters
| Type | Name | Description |
|---|---|---|
text or number | value | What to print. |
display.display(bool _leaveOn = 0)returns voidDoes a full refresh: sends the frame buffer to the panel. If `_leaveOn` is true, the panel supply stays on after the refresh, which saves time on the next update.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
bool | _leaveOn | Keeps the panel supply on after the update when true. Defaults to 0. |
SdFile()returns NoneCreates a file object for reading and writing files on the card. `SdFile` is part of the SdFat library bundled with the Inkplate library.
ReturnsConstructor; no return value.
file.open(const char *path, oflag_t oflag = O_RDONLY)returns boolOpens a file on the card.
Returns`true` if the file opened.
Parameters
| Type | Name | Description |
|---|---|---|
const char * | path | File name or path on the card. |
oflag_t | oflag | How to open the file, for example O_RDONLY. Defaults to O_RDONLY. |
display.sdCardSleep()returns voidTurns off the power to the microSD card and sets the SD interface pins to inputs to save energy.
ReturnsNothing.
file.fileSize()returns uint64_tReturns the size of the open file in bytes.
ReturnsFile size in bytes.
malloc(size_t size)returns void *Standard C function that reserves memory on the heap.
ReturnsPointer to the memory, or `NULL` if there is not enough.
Parameters
| Type | Name | Description |
|---|---|---|
size_t | size | Number of bytes to reserve. |
file.read(void *buf, size_t count)returns intReads bytes from the open file into a buffer.
ReturnsNumber of bytes read, or a negative value on error.
Parameters
| Type | Name | Description |
|---|---|---|
void * | buf | Buffer that receives the data. |
size_t | count | Number of bytes to read. |
file.close()returns boolCloses the open file. Close a file after writing to avoid corrupting it.
Returns`true` if the file closed.
display.image.drawPngFromBuffer(uint8_t *buf, int32_t len, int x, int y, bool dither = 0, bool invert = 0)returns boolDecodes a PNG that is already in memory and draws it.
Returns`true` if the PNG drew, `false` if decoding failed.
Parameters
| Type | Name | Description |
|---|---|---|
uint8_t * | buf | Buffer that holds the whole PNG file. |
int32_t | len | Size of the PNG data in bytes. |
int | x | Left position in pixels. |
int | y | Top position in pixels. |
bool | dither | Dithers the image when true. Defaults to 0. |
bool | invert | Swaps black and white when true. Defaults to 0. |
free(void *ptr)returns voidStandard C function that releases memory reserved with `malloc()`.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
void * | ptr | Pointer returned by malloc(). |
What to expect
Put a PNG named image.png in the root of the card. The display shows the image. The whole file is loaded into heap memory before it is decoded, so it has to fit in the free RAM (the example header gives about 300 KB free heap on the ESP32). The PNG should not be larger than 1200 x 825 pixels. The example reports problems on the display: SD card error!, Cannot open image.png, Not enough RAM for image buffer! or PNG decode error.