|
| 1 | +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
| 2 | +<html lang="en"> |
| 3 | +<head> |
| 4 | +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| 5 | +<meta http-equiv="Content-Style-Type" content="text/css"> |
| 6 | +<link rel="up" title="FatFs" href="../00index.html"> |
| 7 | +<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default"> |
| 8 | +<title>TJpgDec Module Application Note</title> |
| 9 | +</head> |
| 10 | + |
| 11 | + |
| 12 | +<body> |
| 13 | +<h1>TJpgDec Module Application Note</h1> |
| 14 | +<ol class="toc"> |
| 15 | +<li><a href="#use">How to Use</a></li> |
| 16 | +<li><a href="#limits">Limits</a></li> |
| 17 | +<li><a href="#memory">Memory Usage</a></li> |
| 18 | +<li><a href="#opt">Options</a></li> |
| 19 | +<li><a href="#license">About TJpgDec License</a></li> |
| 20 | +</ol> |
| 21 | +<hr> |
| 22 | + |
| 23 | +<div class="para" id="use"> |
| 24 | +<h3>How to Use</h3> |
| 25 | +<p>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.</p> |
| 26 | +<p>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.</p> |
| 27 | +<ol> |
| 28 | +<li>Initialize input stream. (e.g. open a file)</li> |
| 29 | +<li>Allocate JPEG decompression object and work area.</li> |
| 30 | +<li>Call <em>jd_prepare()</em> to analyze and prepare to decompress the JPEG image.</li> |
| 31 | +<li>Initialize output device with the image info in the decompression object.</li> |
| 32 | +<li>Call <em>jd_decomp()</em> to decompress the JPEG image.</li> |
| 33 | +</ol> |
| 34 | + |
| 35 | +<h4>System Organization</h4> |
| 36 | +<p><img src="p1.png" width="420" height="280" alt=""></p> |
| 37 | + |
| 38 | +<h4>Example</h4> |
| 39 | +<pre> |
| 40 | +<span class="c">/*------------------------------------------------*/</span> |
| 41 | +<span class="c">/* TJpgDec Quick Evaluation Program for PCs */</span> |
| 42 | +<span class="c">/*------------------------------------------------*/</span> |
| 43 | + |
| 44 | +<span class="k">#include</span> <stdio.h> |
| 45 | +<span class="k">#include</span> <string.h> |
| 46 | +<span class="k">#include</span> "tjpgd.h" |
| 47 | + |
| 48 | +<span class="c">/* Bytes per pixel of image output */</span> |
| 49 | +<span class="k">#define</span> N_BPP (3 - JD_FORMAT) |
| 50 | + |
| 51 | + |
| 52 | +<span class="c">/* Session identifier for input/output functions (name, members and usage are as user defined) */</span> |
| 53 | +<span class="c"><span class="k">typedef struct</span></span> { |
| 54 | + FILE *fp; <span class="c">/* Input stream */</span> |
| 55 | + uint8_t *fbuf; <span class="c">/* Output frame buffer */</span> |
| 56 | + unsigned int wfbuf; <span class="c">/* Width of the frame buffer [pix] */</span> |
| 57 | +} IODEV; |
| 58 | + |
| 59 | + |
| 60 | +<span class="c">/*------------------------------*/</span> |
| 61 | +<span class="c">/* User defined input funciton */</span> |
| 62 | +<span class="c">/*------------------------------*/</span> |
| 63 | + |
| 64 | +size_t in_func ( <span class="c">/* Returns number of bytes read (zero on error) */</span> |
| 65 | + JDEC* jd, <span class="c">/* Decompression object */</span> |
| 66 | + uint8_t* buff, <span class="c">/* Pointer to the read buffer (null to remove data) */</span> |
| 67 | + size_t nbyte <span class="c">/* Number of bytes to read/remove */</span> |
| 68 | +) |
| 69 | +{ |
| 70 | + IODEV *dev = (IODEV*)jd->device; <span class="c">/* Session identifier (5th argument of jd_prepare function) */</span> |
| 71 | + |
| 72 | + |
| 73 | + <span class="k">if</span> (buff) { <span class="c">/* Raad data from imput stream */</span> |
| 74 | + <span class="k">return</span> fread(buff, 1, nbyte, dev->fp); |
| 75 | + } <span class="k">else</span> { <span class="c">/* Remove data from input stream */</span> |
| 76 | + <span class="k">return</span> fseek(dev->fp, nbyte, SEEK_CUR) ? 0 : nbyte; |
| 77 | + } |
| 78 | +} |
| 79 | + |
| 80 | + |
| 81 | +<span class="c">/*------------------------------*/</span> |
| 82 | +<span class="c">/* User defined output funciton */</span> |
| 83 | +<span class="c">/*------------------------------*/</span> |
| 84 | + |
| 85 | +int out_func ( <span class="c">/* Returns 1 to continue, 0 to abort */</span> |
| 86 | + JDEC* jd, <span class="c">/* Decompression object */</span> |
| 87 | + void* bitmap, <span class="c">/* Bitmap data to be output */</span> |
| 88 | + JRECT* rect <span class="c">/* Rectangular region of output image */</span> |
| 89 | +) |
| 90 | +{ |
| 91 | + IODEV *dev = (IODEV*)jd->device; <span class="c">/* Session identifier (5th argument of jd_prepare function) */</span> |
| 92 | + uint8_t *src, *dst; |
| 93 | + uint16_t y, bws; |
| 94 | + unsigned int bwd; |
| 95 | + |
| 96 | + |
| 97 | + <span class="c">/* Progress indicator */</span> |
| 98 | + <span class="k">if</span> (rect->left == 0) { |
| 99 | + printf("\r%lu%%", (rect->top << jd->scale) * 100UL / jd->height); |
| 100 | + } |
| 101 | + |
| 102 | + <span class="c">/* Copy the output image rectangle to the frame buffer */</span> |
| 103 | + src = (uint8_t*)bitmap; <span class="c">/* Output bitmap */</span> |
| 104 | + dst = dev->fbuf + N_BPP * (rect->top * dev->wfbuf + rect->left); <span class="c">/* Left-top of rectangle in the frame buffer */</span> |
| 105 | + bws = N_BPP * (rect->right - rect->left + 1); <span class="c">/* Width of the rectangle [byte] */</span> |
| 106 | + bwd = N_BPP * dev->wfbuf; <span class="c">/* Width of the frame buffer [byte] */</span> |
| 107 | + <span class="k">for</span> (y = rect->top; y <= rect->bottom; y++) { |
| 108 | + memcpy(dst, src, bws); <span class="c">/* Copy a line */</span> |
| 109 | + src += bws; dst += bwd; <span class="c">/* Next line */</span> |
| 110 | + } |
| 111 | + |
| 112 | + <span class="k">return</span> 1; <span class="c">/* Continue to decompress */</span> |
| 113 | +} |
| 114 | + |
| 115 | + |
| 116 | +<span class="c">/*------------------------------*/</span> |
| 117 | +<span class="c">/* Program Main */</span> |
| 118 | +<span class="c">/*------------------------------*/</span> |
| 119 | + |
| 120 | +int main (int argc, char* argv[]) |
| 121 | +{ |
| 122 | + JRESULT res; <span class="c">/* Result code of TJpgDec API */</span> |
| 123 | + JDEC jdec; <span class="c">/* Decompression object */</span> |
| 124 | + void *work; <span class="c">/* Pointer to the work area */</span> |
| 125 | + size_t sz_work = 3500; <span class="c">/* Size of work area */</span> |
| 126 | + IODEV devid; <span class="c">/* Session identifier */</span> |
| 127 | + |
| 128 | + |
| 129 | + <span class="c">/* Initialize input stream */</span> |
| 130 | + <span class="k">if</span> (argc < 2) <span class="k">return</span> -1; |
| 131 | + devid.fp = fopen(argv[1], "rb"); |
| 132 | + <span class="k">if</span> (!devid.fp) <span class="k">return</span> -1; |
| 133 | + |
| 134 | + <span class="c">/* Prepare to decompress */</span> |
| 135 | + work = (void*)malloc(sz_work); |
| 136 | + res = <span class="b">jd_prepare</span>(&jdec, in_func, work, sz_work, &devid); |
| 137 | + <span class="k">if</span> (res == JDR_OK) { |
| 138 | + <span class="c">/* It is ready to dcompress and image info is available here */</span> |
| 139 | + 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); |
| 140 | + |
| 141 | + <span class="c">/* Initialize output device */</span> |
| 142 | + devid.fbuf = (uint8_t*)malloc(N_BPP * jdec.width * jdec.height); <span class="c">/* Create frame buffer for output image */</span> |
| 143 | + devid.wfbuf = jdec.width; |
| 144 | + |
| 145 | + res = <span class="b">jd_decomp</span>(&jdec, out_func, 0); <span class="c">/* Start to decompress with 1/1 scaling */</span> |
| 146 | + <span class="k">if</span> (res == JDR_OK) { |
| 147 | + <span class="c">/* Decompression succeeded. You have the decompressed image in the frame buffer here. */</span> |
| 148 | + printf("\rDecompression succeeded.\n"); |
| 149 | + |
| 150 | + } <span class="k">else</span> { |
| 151 | + printf("jd_decomp() failed (rc=%d)\n", res); |
| 152 | + } |
| 153 | + |
| 154 | + free(devid.fbuf); <span class="c">/* Discard frame buffer */</span> |
| 155 | + |
| 156 | + } <span class="k">else</span> { |
| 157 | + printf("jd_prepare() failed (rc=%d)\n", res); |
| 158 | + } |
| 159 | + |
| 160 | + free(work); <span class="c">/* Discard work area */</span> |
| 161 | + |
| 162 | + fclose(devid.fp); <span class="c">/* Close the JPEG file */</span> |
| 163 | + |
| 164 | + <span class="k">return</span> res; |
| 165 | +} |
| 166 | +</pre> |
| 167 | + |
| 168 | +</div> |
| 169 | + |
| 170 | +<div class="para" id="limits"> |
| 171 | +<h3>Limits</h3> |
| 172 | +<ul> |
| 173 | +<li>JPEG standard: Baseline only. Progressive and Lossless JPEG format are not supported.</li> |
| 174 | +<li>Image size: Upto 65520 x 65520 pixels.</li> |
| 175 | +<li>Colorspace: Y-Cb-Cr (color) and Grayscale (monochrome).</li> |
| 176 | +<li>Sampling factor: 4:4:4, 4:2:2, 4:2:2(V) or 4:2:0 for color image.</li> |
| 177 | +</ul> |
| 178 | +</div> |
| 179 | + |
| 180 | +<div class="para" id="memory"> |
| 181 | +<h3>Memory Usage</h3> |
| 182 | +<p>These are the memory usage of some platforms at default configuration. Each compilations are optimized in code size.</p> |
| 183 | +<table class="lst2"> |
| 184 | +<tr><th></th><th>AVR</th><th>PIC24</th><th>CM0</th><th>IA-32</th></tr> |
| 185 | +<tr><td>Compiler</td><td>GCC</td><td>C30</td><td>GCC</td><td>MSC</td></tr> |
| 186 | +<tr class="lst3"><td>text+const</td><td>6.1k</td><td>5.1k</td><td>3.1k</td><td>3.7k</td></tr> |
| 187 | +</table> |
| 188 | +<p>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 <tt>JD_SZBUF</tt> and <tt>JD_FASTDECODE</tt>.</p> |
| 189 | +</div> |
| 190 | + |
| 191 | + |
| 192 | +<div class="para" id="opt"> |
| 193 | +<h3>Options</h3> |
| 194 | +<p>TJpgDec has some configuration options on output format, performance and memory usage. These options are in <tt>tjpgdcnf.h</tt>.</p> |
| 195 | +<dl> |
| 196 | +<dt>JD_SZBUF</dt> |
| 197 | +<dd>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.</dd> |
| 198 | +<dt>JD_FORMAT</dt> |
| 199 | +<dd>This option speficies the output pixel format. 0:RGB888, 1:RGB565 or 2:Grayscale.</dd> |
| 200 | +<dt>JD_USE_SCALE</dt> |
| 201 | +<dd>This option switches output scaling feature. When enabled (1), the output image can be descaled on decompression. The descaling ratio is specified in <tt>jd_decomp</tt> function.</dd> |
| 202 | +<dt>JD_FASTDECODE</dt> |
| 203 | +<dd><img class="rset" src="opt.png" width="512" height="264" alt="">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 <tt>6 << HUFF_BITS</tt>, 6144 by default, bytes of work area.</dd> |
| 204 | +<dt>JD_TBLCLIP</dt> |
| 205 | +<dd>This option switches to use table conversion for saturation alithmetics. It requires 1024 bytes of code size.</dd> |
| 206 | +</dl> |
| 207 | +</div> |
| 208 | + |
| 209 | + |
| 210 | +<div class="para" id="license"> |
| 211 | +<h3>About TJpgDec License</h3> |
| 212 | +<p>This is a copy of the TJpgDec license document that included in the source codes.</p> |
| 213 | +<pre> |
| 214 | +/*----------------------------------------------------------------------------/ |
| 215 | +/ TJpgDec - Tiny JPEG Decompressor R0.xx (C)ChaN, 20xx |
| 216 | +/-----------------------------------------------------------------------------/ |
| 217 | +/ The TJpgDec is a generic JPEG decompressor module for tiny embedded systems. |
| 218 | +/ This is a free software that opened for education, research and commercial |
| 219 | +/ developments under license policy of following terms. |
| 220 | +/ |
| 221 | +/ Copyright (C) 20xx, ChaN, all right reserved. |
| 222 | +/ |
| 223 | +/ * The TJpgDec module is a free software and there is NO WARRANTY. |
| 224 | +/ * No restriction on use. You can use, modify and redistribute it for |
| 225 | +/ personal, non-profit or commercial products UNDER YOUR RESPONSIBILITY. |
| 226 | +/ * Redistributions of source code must retain the above copyright notice. |
| 227 | +/ |
| 228 | +/----------------------------------------------------------------------------*/</pre> |
| 229 | +<p>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.</p> |
| 230 | +</div> |
| 231 | + |
| 232 | +<p class="foot"><a href="../00index.html">Return</a></p> |
| 233 | +</body> |
| 234 | +</html> |
0 commit comments