Skip to main content

PNG from a buffer

What this example shows​

Read a PNG file from the microSD card into a buffer in RAM, then draw it from that buffer. The same technique works for PNG data that arrives from any other source, such as a network connection or a serial transfer, because the drawing function takes a memory buffer rather than a file.

You need a FAT or FAT32 formatted microSD card with a file named image.png on it, inserted in Inkplate. The sketch's comments say the PNG should not exceed 800 x 480 pixels, and that the whole file is loaded into heap memory first, so it has to fit in the free RAM (about 300 KB on the ESP32).

Example code​

Select Board
Inkplate7SPECTRA_PNG_From_Buffer.ino
#include "Inkplate.h"

Inkplate display;

void setup()
{
    display.begin();
    display.clearDisplay();
    display.setTextColor(BLACK);
    display.setTextSize(1);

    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()returns None

Creates the Inkplate object. Inkplate 7SPECTRA has a single six-color mode, so the constructor takes no mode argument.

ReturnsConstructor; no return value.

display.begin()returns void

Initializes the library, the peripherals and the frame buffer. Call it once in setup().

ReturnsNothing.

display.clearDisplay()returns void

Fills the frame buffer with white. It does not change the panel.

ReturnsNothing.

display.setTextColor(uint16_t c)returns void

Sets the text color used for the error messages, here BLACK.

ReturnsNothing.

display.setTextSize(uint8_t s)returns void

Sets the text magnification, here 1.

ReturnsNothing.

display.sdCardInit()returns int16_t

Switches on the microSD card's supply, starts its SPI bus and mounts the card.

Returns1 if the card was initialized, 0 if it failed.

SdFile()returns None

SdFat class, bundled with the Inkplate library: a file object on the microSD card. The sketch creates one as `file`.

ReturnsConstructor; no return value.

file.open(path, mode)returns bool

SdFat function, bundled with the Inkplate library: opens a file on the card. The sketch passes O_RDONLY to open it for reading.

Returnstrue if the file was opened.

file.fileSize()returns uint32_t

SdFat function: returns the size of the open file in bytes. The sketch allocates a buffer of that size.

ReturnsFile size in bytes.

file.read(void *buf, size_t count)returns int

SdFat function: reads up to count bytes from the file into the buffer. The sketch reads the whole file.

ReturnsNumber of bytes read.

file.close()returns bool

SdFat function: closes the file.

Returnstrue on success.

malloc(size_t size) and free(void *ptr)returns void *

C standard library functions: allocate the buffer from heap memory and release it after the picture is drawn. If malloc returns nothing, the sketch shows Not enough RAM for image buffer!.

Returnsmalloc returns the buffer, or NULL when there is not enough memory; free returns nothing.

display.image.drawPngFromBuffer(uint8_t *buf, int32_t len, int x, int y, bool dither = 0, bool invert = 0)returns bool

Decodes a PNG held in memory and draws it into the frame buffer with its top-left corner at (x, y). The sketch passes the buffer and its size, position (0, 0), dithering on and invert off. Colors are mapped to the six panel colors.

Returnstrue if the image was drawn, false if it could not be decoded.

display.sdCardSleep()returns void

Sets the card's SPI pins to inputs and switches off the card's supply, to save power in deep sleep.

ReturnsNothing.

display.println(text)returns size_t

Prints text into the frame buffer and moves to the next line. The sketch uses it for its error messages.

ReturnsNumber of bytes printed.

display.display(bool _leaveOn = 0)returns void

Sends the whole frame buffer to the panel and refreshes it.

ReturnsNothing.

What to expect​

The PNG from the card is shown on the screen, dithered to the panel's six colors. The sketch prints nothing to the Serial Monitor. Problems are shown on the screen instead: SD card error!, Cannot open image.png, Not enough RAM for image buffer! or PNG decode error.

🔗Open the complete example

examples/Inkplate7SPECTRA/Advanced/Other/Inkplate7SPECTRA_PNG_From_Buffer

→