Portable pixmap P4 header file on SD-card¶

The portable pixmap P4 header file on SD-card library saves the screen as a portable pixmap file on the SD-card and loads a portable pixmap file into the frame-buffer, ready to be displayed. Everything is performed dynamically at run-time. It is much faster than BMP, as it reads and writes the frame-buffer directly.

This option only supports the monochrome screens.

Info

This method is not recommended for MCUs, as the management of the SD-card is rather slow and prone to interferences.

The portable pixmap file on SD-card library is available on the Commercial edition. The file is PBM coded.

Configure¶

Warning

Ensure the screen is declared and initialised according to the configuration procedure.

#include "hV_File_P4.h"

The pre-processor statement includes the file library. It should be mentioned after the statement for the screen library.

Danger

This library requires the external SD library to manage the SD-card.

Ensure the external SD library is installed and configured properly.

File_P4 myFile(&myScreen);

The constructor File_Image() sets the link to the screen. It should be mentioned after the constructor of the screen.

uint8_t result = myFile.beginFileSystem(pinCS,
    portSPI,
    pinDetect,
    pinLevel);

if (result != RESULT_SUCCESS)
{
    hV_HAL_Serial_crlf();
    hV_HAL_log(LEVEL_CRITICAL, "SD-card error");
    hV_HAL_exit(0x01);
}

result = myFile.setFolder("Image");

beginFileSystem() checks an SD-card is available and initialises it.

The required parameter is

The first line sets the pin for selecting the SD-card.

It is easily provided with myScreen.getBoardPins().cardCS.

The optional parameters are

The second line sets the number of the SPI port, 0 by default;
The third line sets the pin for the detect signal, NOT_CONNECTED or -1 par default;
The fourth line sets the level of detect signal, LOW by default.

The function returns RESULT_SUCCESS if successful, RESULT_ERROR otherwise.

To obtain the pin for selecting the SD-card, use

uint8_t pinCardCS = myScreen.getBoardPins().cardCS;
uint8_t result = myFile.beginFileSystem(pinCardCS);

setFolder() sets the name of the folder for the files, and creates it if it does not exists.

By default, the files are located under the folder img.

The function returns RESULT_SUCCESS if successful, RESULT_ERROR otherwise.

Use¶

Generate¶

uint8_t result = myFile.saveScreen("File_P4");

saveScreen() saves the screen on the SD-card as a portable pixmap header file.

The function returns RESULT_SUCCESS if successful, RESULT_ERROR otherwise.

The required parameter is

The first line provides the name of the file without the .h extension.

Read¶

uint8_t result = myFile.readScreen("File_P4");

readScreen() displays a portable pixmap file from the SD-card on the frame-buffer, to be displayed with flush().

The required parameter is

The first line provides the name of the file without the .P4 extension.

The function checks the size or the multiplier of the image.

The function returns RESULT_SUCCESS if successful, RESULT_ERROR otherwise.

Terminate¶

uint8_t result = myFile.endFileSystem();

endFileSystem() closes the SD-card.

The function returns RESULT_SUCCESS if successful, RESULT_ERROR otherwise.

Display¶

// Image
#include "File_P4.h"

uint8_t result;
result = myFile.readScreen(File_P4);
if (result == RESULT_SUCCESS)
{
    myScreen.flush();
    wait(4);
}

The application needs to include the header file previously generated.

readScreen() loads the image into the frame-buffer, ready to be displayed.

The header file can also be read with the Serial_Image object, from the 16-bit image implementation on the Serial library.

The function returns RESULT_SUCCESS if successful, RESULT_ERROR otherwise.

Example¶

This is the core of the code from example File_Write_P4.ino.

First, generate the header file.

void fileWriteReadP4()
{
    // Initialise
    uint8_t result;
    result = myFile.beginFileSystem(5);
    if (result != RESULT_SUCCESS)
    {
        hV_HAL_log(LEVEL_ERROR, "SD-card error");
        hV_HAL_Serial_crlf();
        return;
    }

    myScreen.setOrientation(myOrientation);
    myScreen.selectFont(fontLarge);

    myScreen.clear();
    myScreen.gText(8, 8, "File P4");
    myScreen.flushFast();

    // Write to SD-card
    result = myFile.saveScreen("File_P4");
    wait(4);
}

The generated header file contains the pixmap as an array.

// Pixmap as header file generated by hV_File_P4

// SDK
#include "hV_HAL_Peripherals.h"

// Release
#ifndef FILE_P4_FILE_P4_RELEASE
#define FILE_P4_FILE_P4_RELEASE

static const uint8_t P4_File_P4[] =
{
    'P', '4', 0x0a, // P4 header
    '1', '5', '2', ' ', '2', '9', '6', 0x0a, // H x V = 152 296
    // size= 5624
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // v= 0
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // v= 1
    // ...
}

#endif // FILE_P4_FILE_P4_RELEASE

Then, include the header file in the application and build it.

// Image
#include "File_P4.h"

void displayReadHeader()
{
    uint8_t result;

    myScreen.setOrientation(myOrientation);

    myScreen.clear();
    myScreen.gText(4, 4, "Reading the P4 header back...");
    myScreen.flushFast();
    wait(4);

    // Read from MCU Flash
    myScreen.clear();
    result = myFile.readScreen(P4_File_P4);
    if (result == RESULT_SUCCESS)
    {
        myScreen.flush();
        wait(4);
    }
}