TJpg_Decoder Arduino Library

TJpg_Decoder is an Arduino library designed to render JPEG files onto TFT displays. It supports various storage methods including:

• SD cards
• Program memory (FLASH/PROGMEM) arrays
• SPIFFS (ESP32, ESP8266)
• LittleFS (ESP32, ESP8266, RP2040)

The library is optimized for small embedded systems and uses the TJjpgDec decompressor engine.

To ensure successful decoding, your JPEG files must adhere to the following constraints:

• Bit Depth: Must be in 24-bit format. 8-bit JPEGs are not supported.
• Compression Type: Progressive JPEGs are not supported (only baseline JPEGs).

Supported Processors

The library has been tested on:

• Arduino Due
• ESP32 (Requires Arduino board package 2.0.0 or later)
• ESP8266 (e.g., NodeMCU 1.0)
• STM32
• RP2040

Memory Considerations

• RAM: The library requires more RAM than an Arduino UNO provides. It typically uses ~3.5 KB of RAM for workspace (independent of image dimensions).
• ROM: Uses approximately 3.5 KB to 8.5 KB of ROM for text and constants.
• Array Limits: When using memory arrays, note that some Arduino boards have a maximum array size limit of 32,767 bytes (32 KB minus 1 byte).

Platform-Specific Notes

• Arduino Mega: Not recommended. It may fail to decode some images due to RAM shortages. Additionally, if large images in FLASH push the executable code beyond the 64K 16-bit address limit, the Mega will fail to boot.
• Arduino Due: Recommended for larger image sets in FLASH.

If TJPGD_LOAD_FFS is defined (common on ESP8266, ESP32, and RP2040), you can draw images directly from the internal file system using drawFsJpg(). You can pass a filename and specify the file system instance (e.g., LittleFS or SPIFFS).

// Draw from SPIFFS
TJpgDec.drawFsJpg(0, 0, "/image.jpg", SPIFFS);

// Draw from a File object
File myFile = LittleFS.open("/image.jpg", "r");
TJpgDec.drawFsJpg(0, 0, myFile);

Use drawJpg() to decode and render a JPEG image stored in memory (RAM or PROGMEM). You must provide the starting X and Y coordinates, the pointer to the array, and the total size of the array in bytes.

// Assuming 'myJpgData' is a uint8_t array and 'myJpgSize' is its length
TJpgDec.drawJpg(0, 0, myJpgData, myJpgSize);

If TJPGD_LOAD_SD_LIBRARY is defined, you can draw images directly from an SD card using drawSdJpg(). This accepts a filename or a File object from the SD library.

// Draw from SD card filename
TJpgDec.drawSdJpg(0, 0, "/photo.jpg");

// Draw from an SD File object
File mySdFile = SD.open("/photo.jpg");
TJpgDec.drawSdJpg(0, 0, mySdFile);

To render the decoded JPEG data to a display (like a TFT), you must provide a callback function of type SketchCallback. This function is called by the decoder whenever a block of pixels is ready. The callback receives the coordinates (x, y), dimensions (w, h), and a pointer to the pixel data (data).

Register the callback using setCallback().

typedef bool (*SketchCallback)(int16_t x, int16_t y, uint16_t w, uint16_t h, uint16_t *data);

// Example callback implementation
bool myDrawCallback(int16_t x, int16_t y, uint16_t w, uint16_t h, uint16_t *data) {
  // Use your display library to draw the pixels
  // tft.drawRGBBitmap(x, y, data, w, h);
  return true;
}

// Registering the callback
TJpgDec.setCallback(myDrawCallback);

To determine the width and height of a JPEG image without decoding the entire file, use the getJpgSize (for arrays), getFsJpgSize (for FS), or getSdJpgSize (for SD) methods. These methods populate the provided uint16_t pointers.

uint16_t w, h;
// For an array
TJpgDec.getJpgSize(&w, &h, myJpgData, myJpgSize);

// For a file on FS
TJpgDec.getFsJpgSize(&w, &h, "/image.jpg", LittleFS);

The TJpg_Decoder provides two utility methods for adjusting how data is processed:

• setJpgScale(uint8_t scale): Sets the scaling factor (e.g., for downscaling).
• setSwapBytes(bool swap): Toggles byte swapping, which is useful if your display expects a different endianness for 16-bit color data.

TJpgDec.setJpgScale(2); // Scale by 2
TJpgDec.setSwapBytes(true); // Enable byte swapping