Skip to content

README.md

Latest commit

 

History

History
140 lines (96 loc) · 6.45 KB

README.md

File metadata and controls

140 lines (96 loc) · 6.45 KB
Raw

ARCH GUI

Overview

PNGDEC is a PNG decoder that was created to address the challenges of decoding PNG images on devices with limited memory and processing power. Traditional PNG decoders often assume abundant RAM, which is not the case for many embedded systems. This library prioritizes:

  • Ease of Use: Simple API, compatible with Arduino-style C++ and straight C.
  • Performance: Efficient decoding, with benchmarks available for various MCUs.
  • Self-Containment: No heap memory management required, making it suitable for environments without dynamic memory allocation.

Key Features

  • Minimal RAM Usage: Runs on MCUs with as little as 50kB of free RAM.
  • No External Dependencies: Self-contained, with no reliance on malloc/free or other external libraries.
  • Flexible Decoding: Supports both line-by-line decoding (via callback) and direct decoding to a user-supplied buffer.
  • Optimized for Embedded Systems: Designed for Arduino and other embedded platforms, with optional features to improve speed (e.g., disabling zlib’s internal CRC check for a 10-30% performance boost).
  • Wide Compatibility: Works with most standard PNG features (except interlacing, which requires more RAM).
  • Output Flexibility: Provides functions to convert decoded pixels to ARGB4444, ARGB1555, ARGB8888, RGB565, RGB888, A8 formats.

Written by Larry Bank, forked from: https://github.com/bitbank2/PNGdec. This fork brings an adaptation layer to easily plug the decoder to MICROEJ VEE (cf. PNGDEC_decoder.c).

Usage

The bellow steps explain how to integrate PNGDEC to MICROEJ VEE:

  1. These sources can be included in the VEE Port with the method you prefer, by using this repository as a submodule or by doing a copy of the sources in the VEE Port repository.
  2. Add the following code to use the decoder from MICROEJ VEE:
#include "PNGDEC_decoder.h"
#include "LLUI_DISPLAY_impl.h"
// --------------------------------------------------------------------------------
// LLUI_DISPLAY_impl.h functions
// --------------------------------------------------------------------------------

LLUI_DISPLAY_Status LLUI_DISPLAY_IMPL_decodeImage(uint8_t* addr, uint32_t length, MICROUI_ImageFormat expectedFormat, MICROUI_Image* image, bool* isFullyOpaque){
    return PNGDEC_decode(addr, length, expectedFormat, image, isFullyOpaque);  
}

Memory Requirements

The below table provides insights about PNGDEC memory requirements (RAM & ROM).

Note: results obtained with IAR Embedded Workbench 9.30.1 with high speed optimizations enabled.

RAM Usage

PNGDEC allocates dynamically its working buffers inside MICROEJ VEE Images Heap. Allocated size depends on the image width to decode. Working buffers are allocated in PNGDEC_decoder.c. See PNGDEC_configuration.h to define a custom memory allocator for working buffers.

Allocating the working buffers in a high speed RAM region will result in faster decoding operations.

PNGDEC RAM usage breakdown:

Description RAM Usage
Working buffers with constant size (ucZLIB, ucPalette, ucFileBuf) 42 kB
Working buffers depending on image size (pTemp, ucPixels) (width + 4) x 10
Decoded Image Buffer (must be allocated in MICROEJ VEE Images Heap) ((width + bytes for memory alignment) x height x BPP Output Format)/8

ROM Usage

ROM Usage: 30kB

Performance

Test Conditions

  • STM32L4R9-DK (Cortex-M4, 120MHz).
  • PNG Images are stored in external QSPI flash.
  • Images Heap is placed in external RAM.
  • PNGDEC working buffers are allocated in external RAM.

Decoding Time Depending on PNGDEC Working Buffers Location

Example with a 390x390 image decoded in RGB565 format:

  • Total Heap usage: ~310kB
  • Decoding time with PNGDEC working buffers located in internal RAM: 170ms
  • Decoding time with PNGDEC working buffers located in external RAM: 530ms

Decoding Time Depending on Image Resolution

Configuration:

  • Image compression level 6 with default strategy, no filter, 32-bit RGB+alpha, non-interlaced.
  • Image decoded in ARGB8888 format.
Image Resolution Decode Duration (ms) Heap Usage (Kbytes)
64x64 60 18.29
128x128 137 66.90
256x256 369 260.16
390x390 736 599.61

Supported PNG Images

For optimization purpose, not all PNG encoding formats are supported by PNGDEC.

Refer to the PNGDEC testsuite report file to verify which encodings are supported.

Requirements

N/A

Validation

Here is a non exhaustive list of tested environments:

  • VEE Port:
    • STM32L4R9-DK VEE Port 2.0.0
  • Compilers / Integrated Development Environments:
    • IAR Embedded Workbench 9.30.1

MISRA Compliance

Please contact MicroEJ support for a Misra Compliant version of this implementation.

Dependencies

Put here the list of dependencies of the C module.

Source

N/A

Restrictions

None.

Copyright 2025 MicroEJ Corp. This file has been modified and/or created by MicroEJ Corp. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.