TJpgDec is a generic JPEG image decompressor module that highly optimized for small embedded systems. It works with very low memory consumption, so that it can be incorporated into tiny microcontrollers, such as AVR, 8051, PIC, Z80, Cortex-M0 and etc.
-
-
Features
-
-
Platform independent. Written in plain C (C99).
-
Easy to use master mode operation.
-
Fully re-entrant architecture.
-
Configurable optimization level for both 8/16-bit and 32-bit MCU.
-
Very small memory footprint:
-
-
3.5K bytes of RAM for work area independent of image dimensions.
-
3.5-8.5K bytes of ROM for text and constants.
-
-
-
Output format:
-
-
Pixel format: RGB888, RGB565 or Grayscale pre-configurable.
-
Scaling ratio: 1/1, 1/2, 1/4 or 1/8 selectable on decompression.
-
-
-
-
-
-
-
-
Application Interface
-
There are two API functions to analyze and decompress the JPEG image.
-
-
jd_prepare - Prepare decompression of the JPEG image
-
jd_decomp - Execute decompression of the JPEG image
-
-
-
-
-
-
I/O functions
-
To input the JPEG data and output the decompressed image, TJpgDec requires two user defined I/O functions. These are called back from the TJpgDec module in the decompression process.
Output Function - Output the decompressed image to the destination object
-
-
-
-
-
-
Resources
-
The TJpgDec module is a free software opened for education, research and development. You can use, modify and/or redistribute it for personal projects or commercial products without any restriction under your responsibility.
First of all, you should build and run the sample program shown below. This is a typical usage of TJpgDec module and it helps to narrow down the problem on debugging.
-
The decompression session is divided in two stages. The first stage is to analyze the JPEG image and the second stage is to decompress it.
-
-
Initialize input stream. (e.g. open a file)
-
Allocate JPEG decompression object and work area.
-
Call jd_prepare() to analyze and prepare to decompress the JPEG image.
-
Initialize output device with the image info in the decompression object.
-
Call jd_decomp() to decompress the JPEG image.
-
-
-
System Organization
-
-
-
Example
-
-/*------------------------------------------------*/
-/* TJpgDec Quick Evaluation Program for PCs */
-/*------------------------------------------------*/
-
-#include <stdio.h>
-#include <string.h>
-#include "tjpgd.h"
-
-/* Bytes per pixel of image output */
-#define N_BPP (3 - JD_FORMAT)
-
-
-/* Session identifier for input/output functions (name, members and usage are as user defined) */
-typedef struct {
- FILE *fp; /* Input stream */
- uint8_t *fbuf; /* Output frame buffer */
- unsigned int wfbuf; /* Width of the frame buffer [pix] */
-} IODEV;
-
-
-/*------------------------------*/
-/* User defined input funciton */
-/*------------------------------*/
-
-size_t in_func ( /* Returns number of bytes read (zero on error) */
- JDEC* jd, /* Decompression object */
- uint8_t* buff, /* Pointer to the read buffer (null to remove data) */
- size_t nbyte /* Number of bytes to read/remove */
-)
-{
- IODEV *dev = (IODEV*)jd->device; /* Session identifier (5th argument of jd_prepare function) */
-
-
- if (buff) { /* Raad data from imput stream */
- return fread(buff, 1, nbyte, dev->fp);
- } else { /* Remove data from input stream */
- return fseek(dev->fp, nbyte, SEEK_CUR) ? 0 : nbyte;
- }
-}
-
-
-/*------------------------------*/
-/* User defined output funciton */
-/*------------------------------*/
-
-int out_func ( /* Returns 1 to continue, 0 to abort */
- JDEC* jd, /* Decompression object */
- void* bitmap, /* Bitmap data to be output */
- JRECT* rect /* Rectangular region of output image */
-)
-{
- IODEV *dev = (IODEV*)jd->device; /* Session identifier (5th argument of jd_prepare function) */
- uint8_t *src, *dst;
- uint16_t y, bws;
- unsigned int bwd;
-
-
- /* Progress indicator */
- if (rect->left == 0) {
- printf("\r%lu%%", (rect->top << jd->scale) * 100UL / jd->height);
- }
-
- /* Copy the output image rectangle to the frame buffer */
- src = (uint8_t*)bitmap; /* Output bitmap */
- dst = dev->fbuf + N_BPP * (rect->top * dev->wfbuf + rect->left); /* Left-top of rectangle in the frame buffer */
- bws = N_BPP * (rect->right - rect->left + 1); /* Width of the rectangle [byte] */
- bwd = N_BPP * dev->wfbuf; /* Width of the frame buffer [byte] */
- for (y = rect->top; y <= rect->bottom; y++) {
- memcpy(dst, src, bws); /* Copy a line */
- src += bws; dst += bwd; /* Next line */
- }
-
- return 1; /* Continue to decompress */
-}
-
-
-/*------------------------------*/
-/* Program Main */
-/*------------------------------*/
-
-int main (int argc, char* argv[])
-{
- JRESULT res; /* Result code of TJpgDec API */
- JDEC jdec; /* Decompression object */
- void *work; /* Pointer to the work area */
- size_t sz_work = 3500; /* Size of work area */
- IODEV devid; /* Session identifier */
-
-
- /* Initialize input stream */
- if (argc < 2) return -1;
- devid.fp = fopen(argv[1], "rb");
- if (!devid.fp) return -1;
-
- /* Prepare to decompress */
- work = (void*)malloc(sz_work);
- res = jd_prepare(&jdec, in_func, work, sz_work, &devid);
- if (res == JDR_OK) {
- /* It is ready to dcompress and image info is available here */
- printf("Image size is %u x %u.\n%u bytes of work ares is used.\n", jdec.width, jdec.height, sz_work - jdec.sz_pool);
-
- /* Initialize output device */
- devid.fbuf = (uint8_t*)malloc(N_BPP * jdec.width * jdec.height); /* Create frame buffer for output image */
- devid.wfbuf = jdec.width;
-
- res = jd_decomp(&jdec, out_func, 0); /* Start to decompress with 1/1 scaling */
- if (res == JDR_OK) {
- /* Decompression succeeded. You have the decompressed image in the frame buffer here. */
- printf("\rDecompression succeeded.\n");
-
- } else {
- printf("jd_decomp() failed (rc=%d)\n", res);
- }
-
- free(devid.fbuf); /* Discard frame buffer */
-
- } else {
- printf("jd_prepare() failed (rc=%d)\n", res);
- }
-
- free(work); /* Discard work area */
-
- fclose(devid.fp); /* Close the JPEG file */
-
- return res;
-}
-
-
-
-
-
-
Limits
-
-
JPEG standard: Baseline only. Progressive and Lossless JPEG format are not supported.
-
Image size: Upto 65520 x 65520 pixels.
-
Colorspace: Y-Cb-Cr (color) and Grayscale (monochrome).
-
Sampling factor: 4:4:4, 4:2:2, 4:2:2(V) or 4:2:0 for color image.
-
-
-
-
-
Memory Usage
-
These are the memory usage of some platforms at default configuration. Each compilations are optimized in code size.
-
-
AVR
PIC24
CM0
IA-32
-
Compiler
GCC
C30
GCC
MSC
-
text+const
6.1k
5.1k
3.1k
3.7k
-
-
TJpgDec requires a work area upto 3100 bytes for most JPEG images. It exactly depends on what parameter has been used to create the JPEG image to be decompressed. The 3100 bytes is the maximum memory requirement in default configuration and it varies depends on JD_SZBUF and JD_FASTDECODE.
-
-
-
-
-
Options
-
TJpgDec has some configuration options on output format, performance and memory usage. These options are in tjpgdcnf.h.
-
-
JD_SZBUF
-
This option speficies how many bytes read from input stream at a time. TJpgDec alignes each read request to the buffer size, so that 512, 1024, 2048... byte is ideal to read data from the storage device.
-
JD_FORMAT
-
This option speficies the output pixel format. 0:RGB888, 1:RGB565 or 2:Grayscale.
-
JD_USE_SCALE
-
This option switches output scaling feature. When enabled (1), the output image can be descaled on decompression. The descaling ratio is specified in jd_decomp function.
-
JD_FASTDECODE
-
This option switches the decompression algorithm. How this option affects the performance is highly depends on the processor architectre as shown in right image. The Lv.0 is the basic optimization in minimal memory usage suitable for 8/16-bit processors. The Lv.1 depends on 32-bit barrel shifter and is suitable for 32-bit processors. It requires additional 320 bytes of work area. The Lv.2 enables the table conversion for huffman decoding. It requires additional 6 << HUFF_BITS, 6144 by default, bytes of work area.
-
JD_TBLCLIP
-
This option switches to use table conversion for saturation alithmetics. It requires 1024 bytes of code size.
-
-
-
-
-
-
About TJpgDec License
-
This is a copy of the TJpgDec license document that included in the source codes.
-
-/*----------------------------------------------------------------------------/
-/ TJpgDec - Tiny JPEG Decompressor R0.xx (C)ChaN, 20xx
-/-----------------------------------------------------------------------------/
-/ The TJpgDec is a generic JPEG decompressor module for tiny embedded systems.
-/ This is a free software that opened for education, research and commercial
-/ developments under license policy of following terms.
-/
-/ Copyright (C) 20xx, ChaN, all right reserved.
-/
-/ * The TJpgDec module is a free software and there is NO WARRANTY.
-/ * No restriction on use. You can use, modify and redistribute it for
-/ personal, non-profit or commercial products UNDER YOUR RESPONSIBILITY.
-/ * Redistributions of source code must retain the above copyright notice.
-/
-/----------------------------------------------------------------------------*/
-
Therefore TJpgDec license is one of the BSD-style license but there is a significant difference. Because TJpgDec is for embedded projects, so that the conditions for redistributions in binary form, such as embedded code, hex file and binary library, are not specified in order to maximize its usability. The documentation of the distributions may or may not include about TJpgDec and its license document. Of course TJpgDec is compatible with the projects under GNU GPL. When redistribute TJpgDec with any modification, the license can also be changed to GNU GPL or any BSD-style license.
The jd_decomp function decompress the JPEG image and output it as pixel data.
-
-JRESULT jd_decomp (
- JDEC* jdec, /* Pointer to valid decompression object */
- int(*outfunc)(JDEC*,void*,JRECT*), /* Pointer to output function */
- uint8_t scale/* Scaling factor */
-);
-
-
-
-
-
Parameters
-
-
jdec
-
Specifies the valid decompressor object.
-
outfunc
-
Specifies the user defined data output function. The jd_decomp function calls this function to output the decompressed JPEG image in pre-defined pixel format.
-
scale
-
Specifies scaling factor N for output. The output image is descaled to 1/2N (N = 0 to 3). When scaling feature is disabled (JD_USE_SCALE == 0), it must be 0.
-
-
-
-
-
-
Return Values
-
-
JDR_OK
-
Function succeeded.
-
JDR_INTR
-
The decompression process was interrupted by output function.
-
JDR_INP
-
An error occured in input function due to hard error or wrong stream termination.
-
JDR_PAR
-
Parameter error. Given scale factor is invalid.
-
JDR_FMT1
-
Data format error. The input JPEG data can be collapted.
-
-
-
-
-
-
Description
-
The jd_decomp function is the second stage of a JPEG decompression session. It decompresses the input JPEG stream and outputs it via user defined output function. After this function, the decompressor object is no longer valid.
-
The scaling factor can be specified on decompresson. It descales the size of the output image by 1/2, 1/4 or 1/8. For example, when decompress a JPEG image of 1024x768 in 1/4 scaling, the decmopressed image will be output in 256x192. The scaling ratio of 1/2 and 1/4 will slightly decrease the decompression speed compared to 1/1 due to averaging process. However scaling ratio of 1/8 will 2-3 times faster than 1/1, because IDCT and averaging process for each block can be skipped. This characteristic is sutable to create thumbnails.
User defined input function to read data from input stream.
-
-size_t in_func (
- JDEC* jdec, /* Pointer to the decompression object */
- uint8_t* buff, /* Pointer to buffer to store the read data */
- size_t ndata/* Number of bytes to read/remove */
-);
-
-
-
-
-
-
Parameters
-
-
jdec
-
Decompression object of this session.
-
buff
-
Points the read buffer to store the data read form the input stream. A null pointer specifies to remove the data from the input stream.
-
ndata
-
Number of bytes to read/remove from the input stream.
-
-
-
-
-
-
Return Values
-
Returns number of bytes read/removed. If any value not expected is returned, the jd_prepare and jd_decomp function aborts with JDR_INP.
-
-
-
-
-
Description
-
This function is the data input interface of the TJpgDec module. The corresponding decompression session can be identified by the session identifier jdec->device passed to the 5th argument of jd_prepare function.
The JDEC structure holds the data, pointer and flags to manage the decompression session. Application program must not change any member in this structure.
-
-typedefstruct JDEC JDEC;
-struct JDEC {
- size_t dctr; /* Number of bytes available in the input buffer */
- uint8_t* dptr; /* Current data read ptr */
- uint8_t* inbuf; /* Bit stream input buffer */
- uint8_t dmsk; /* Current bit in the current read byte */
- uint8_t scale; /* Output scaling ratio */
- uint8_t msx, msy; /* MCU size in unit of block (width, height) */
- uint8_t qtid[3]; /* Quantization table ID of each component */
- uint8_t ncomp; /* Number of color components (1:grayscale, 3:color) */
- int16_t dcv[3]; /* Previous DC element of each component */
- uint16_t nrst; /* Restart inverval */
- uint16_t width, height; /* Size of the input image (pixel) */
- uint8_t* huffbits[2][2]; /* Huffman bit distribution tables [yc][dcac] */
- uint16_t* huffcode[2][2]; /* Huffman code word tables [yc][dcac] */
- uint8_t* huffdata[2][2]; /* Huffman decoded data tables [yc][dcac] */
- int32_t* qttbl[4]; /* De-quaitizer tables [id] */
- void* workbuf; /* Working buffer for IDCT and RGB output */
- uint8_t* mcubuf; /* Working buffer for the MCU */
- void* pool; /* Pointer to available memory pool */
- size_t sz_pool; /* Size of momory pool (bytes available) */
- size_t (*infunc)(JDEC*, uint8_t*, size_t); /* Pointer to jpeg stream input function */
- void* device; /* Pointer to I/O device identifiler for the session */
-};
-
User defined output function to write decompressed pixels to the output device.
-
-int out_func (
- JDEC* jdec, /* Pointer to the decompression object */
- void* bitmap, /* Bitmap to be output */
- JRECT* rect/* Rectangle to output */
-);
-
-
-
-
-
Parameters
-
-
jdec
-
Decompression object of this session.
-
bitmap
-
Decompressed image to be output.
-
rect
-
Specifies output rectangle where in the image. Type is defined in tjpgd.h
-
-
-
-
-
-
Return Values
-
Normally returns 1. It lets TJpgDec to continue the decompressing process. If a 0 is returned, jd_decomp function aborts with JDR_INTR. This is useful to interrupt the decompression process.
-
-
-
-
-
Description
-
This function is the data output interface of the TJpgDec module. The corresponding decompression session can be identified by the session identifier jdec->device passed to the 5th argument of jd_prepare function.
-
The bitmap is sent to the frame buffer or display device in this function. The first pixel in the bitmap is the left-top of the rectangular, the second one is next right and last pixel is the bottom-right of the rectangle. Because the JPEG image is compressed and streamed in unit of MCU (Minimum Coded Unit), TJpgDec outputs the image in MCU by MCU. The size of MCU depends on the sampling factor of JPEG compression, typically in 8x8, 16x8 or 16x16, but the rectangles on right end and bottom end of the image will be clipped.
-
The output pixel format is defined by JD_FORMAT option in the tjpgdcnf.h as shown below.
The jd_prepare function analyzes the JPEG data and create a decompression object for subsequnet decompression process.
-
-JRESULT jd_prepare (
- JDEC* jdec, /* Pointer to blank decompression object */
- size_t (*infunc)(JDEC*, uint8_t*, size_t), /* Pointer to input function */
- void* work, /* Pointer to the work area */
- size_t sz_work, /* Size of the work area */
- void* device/* Session identifier for the session */
-);
-
-
-
-
-
Parameters
-
-
jdec
-
Specifies the decompression object to be initialized. The decompression object is used by subsequent decompression process.
-
input
-
Pointer to the user defined data input function. The jd_prepare and jd_decomp function call this function to read the JPEG data from the input stream.
-
work
-
Pointer to the work area for this session. It should be aligned to the word boundary, or it can result a hard fault on some processors.
-
sz_work
-
Size of the work area in unit of byte. TJpgDec requires upto 3092 bytes of work area depends on the built-in parameter tables of the JPEG image to deccompress.
-
device
-
Pointer to the user defined session identifier for this session. It is stored to the member device in the decompression object. It can be refered by I/O functions to identify the corresponding session. If this feature is not needed, set null and do not care about this.
-
-
-
-
-
-
Return Values
-
-
JDR_OK
-
Function succeeded and the decompression object is valid.
-
JDR_INP
-
An error occured in input function due to a hard error or wrong stream termination.
-
JDR_MEM1
-
Insufficient work area for this JPEG image.
-
JDR_MEM2
-
Insufficient input buffer for this JPEG image. JD_SZBUF may be too small.
-
JDR_FMT1
-
Data format error. The JPEG data can be collapted.
-
JDR_FMT3
-
Not supported JPEG standard. May be a progressive JPEG image.
-
-
-
-
-
Description
-
The jd_prepare function is the first stage of a JPEG decompression session. It analyzes the JPEG image and create parameter tables for decompression. After the function succeeded, the session gets ready to decompress the JPEG image by the jd_decomp fnction. The application program can refer the dimensions of the JPEG image stored in the decompression object. These information will be used to configure the output device and parameters for subsequent decompression stage.
-
-
diff --git a/core/embed/extmod/modtrezorui/tjpgd/src/tjpgd.c b/core/embed/extmod/modtrezorui/tjpgd/tjpgd.c
similarity index 100%
rename from core/embed/extmod/modtrezorui/tjpgd/src/tjpgd.c
rename to core/embed/extmod/modtrezorui/tjpgd/tjpgd.c
diff --git a/core/embed/extmod/modtrezorui/tjpgd/src/tjpgd.h b/core/embed/extmod/modtrezorui/tjpgd/tjpgd.h
similarity index 100%
rename from core/embed/extmod/modtrezorui/tjpgd/src/tjpgd.h
rename to core/embed/extmod/modtrezorui/tjpgd/tjpgd.h
diff --git a/core/embed/extmod/modtrezorui/tjpgd/src/tjpgdcnf.h b/core/embed/extmod/modtrezorui/tjpgd/tjpgdcnf.h
similarity index 100%
rename from core/embed/extmod/modtrezorui/tjpgd/src/tjpgdcnf.h
rename to core/embed/extmod/modtrezorui/tjpgd/tjpgdcnf.h
-
This option switches the decompression algorithm. How this option affects the performance is highly depends on the processor architectre as shown in right image. The Lv.0 is the basic optimization in minimal memory usage suitable for 8/16-bit processors. The Lv.1 depends on 32-bit barrel shifter and is suitable for 32-bit processors. It requires additional 320 bytes of work area. The Lv.2 enables the table conversion for huffman decoding. It requires additional 6 << HUFF_BITS, 6144 by default, bytes of work area.