Zum Hauptinhalt springen

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.

Select Board
Inkplate10_PNG_From_Buffer.ino
#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 None

Creates 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

TypeNameDescription
uint8_tmodeINKPLATE_1BIT or INKPLATE_3BIT.
display.begin()returns void

Initializes the library and the display. Call it once, at the start of `setup()`.

ReturnsNothing.

display.clearDisplay()returns void

Clears the frame buffer in memory. It does not change what the panel shows until you call `display()`.

ReturnsNothing.

display.setTextColor(uint16_t c)returns void

Sets the text color.

ReturnsNothing.

Parameters

TypeNameDescription
uint16_tcText color, for example BLACK.
display.setTextSize(uint8_t s)returns void

Scales text by an integer factor. The base font is 5 x 7 pixels.

ReturnsNothing.

Parameters

TypeNameDescription
uint8_tsScale factor.
display.sdCardInit()returns int16_t

Powers the microSD card and starts the SD interface.

Returns`1` if the card initialized, `0` if it failed.

display.println(value)returns size_t

Same 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

TypeNameDescription
text or numbervalueWhat to print.
display.display(bool _leaveOn = 0)returns void

Does 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

TypeNameDescription
bool_leaveOnKeeps the panel supply on after the update when true. Defaults to 0.
SdFile()returns None

Creates 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 bool

Opens a file on the card.

Returns`true` if the file opened.

Parameters

TypeNameDescription
const char *pathFile name or path on the card.
oflag_toflagHow to open the file, for example O_RDONLY. Defaults to O_RDONLY.
display.sdCardSleep()returns void

Turns off the power to the microSD card and sets the SD interface pins to inputs to save energy.

ReturnsNothing.

file.fileSize()returns uint64_t

Returns 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

TypeNameDescription
size_tsizeNumber of bytes to reserve.
file.read(void *buf, size_t count)returns int

Reads bytes from the open file into a buffer.

ReturnsNumber of bytes read, or a negative value on error.

Parameters

TypeNameDescription
void *bufBuffer that receives the data.
size_tcountNumber of bytes to read.
file.close()returns bool

Closes 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 bool

Decodes a PNG that is already in memory and draws it.

Returns`true` if the PNG drew, `false` if decoding failed.

Parameters

TypeNameDescription
uint8_t *bufBuffer that holds the whole PNG file.
int32_tlenSize of the PNG data in bytes.
intxLeft position in pixels.
intyTop position in pixels.
boolditherDithers the image when true. Defaults to 0.
boolinvertSwaps black and white when true. Defaults to 0.
free(void *ptr)returns void

Standard C function that releases memory reserved with `malloc()`.

ReturnsNothing.

Parameters

TypeNameDescription
void *ptrPointer 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.