-
Notifications
You must be signed in to change notification settings - Fork 1
/
libjpeg.html
194 lines (187 loc) · 9.88 KB
/
libjpeg.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title> libjpeg - JPEG encoding & decoding </title>
<script src="jquery.js"></script>
<script src="jquery-cookie.js"></script>
<script src="jquery-tablesorter.js"></script>
<script src="strftime.js"></script>
<script src="mustache.js"></script>
<script src="config.js"></script>
<script src="main.js"></script>
<link rel="stylesheet" type="text/css" href="templates/reset.css" />
<link rel="stylesheet" type="text/css" href="templates/hack.css" />
<link rel="stylesheet" type="text/css" id="lights_css" />
<script>
var DOCNAME = 'libjpeg'
var PROJECT = 'libjpeg'
//set the lights before rendering starts
set_lights()
</script>
</head>
<body>
<header>
<div class="container">
<div class="btn-container btn-lights-container">
<a href="#" class="btn btn-lights" id="lights">lights</a>
</div>
<div class="btn-container btn-home-container">
<a href="/" class="btn btn-home">luapower</a>
</div>
<table id="header_table">
<tr>
<td style="vertical-align: middle;" width="100%">
<h1> libjpeg </h1>
<h2> JPEG encoding & decoding </h2>
</td>
<td style="vertical-align: middle;" align="right" style="height: 150px">
<table><tr><td>
<div class="doc" id="package_info_container">
<div id="package_info"> </div>
<div id="commit_log"> </div>
</div>
<a href="https://github.com/luapower/libjpeg" class="btn btn-rightside btn-github"><span class="icon"></span>View on GitHub</a>
</td></tr><tr><td>
<a href="https://github.com/luapower/libjpeg/tarball/master" class="btn btn-rightside">Download as .tar.gz</a>
</td></tr><tr><td>
<a href="https://github.com/luapower/libjpeg/zipball/master" class="btn btn-rightside">Download as .zip</a>
</td></tr></table>
</td>
</tr>
</table>
<div class="btn-container btn-discuss-container">
<a href="https://github.com/luapower/libjpeg/issues/new" target="_blank"
class="btn btn-rightside btn-discuss"><span class="icon"></span>Discuss</a>
</div>
</div>
</header>
<div class="bg-container">
<div class="bg-center-container">
<div class="bg bg-libjpeg" style="background-image: url('bg/libjpeg.png');"></div>
</div>
</div>
<div class="under-header">
<div class="container">
<div id="toc_container" class="toc_container doc"></div>
<button id=tab1_button class="tab_button hidden">Documentation</button>
<button id=tab2_button class="tab_button hidden">Package Info</button>
<div id="tabs_cointainer">
<div id="tab1_container">
<section class="doc">
<span id="module_info"></span>
<h2 id="local-libjpeg-requirelibjpeg"><code>local libjpeg = require'libjpeg'</code></h2>
<p>A ffi binding for the <a href="http://libjpeg.sourceforge.net/">libjpeg</a> 6.2 API. Comes with <a href="http://www.libjpeg-turbo.org/">libjpeg-turbo</a> binaries.</p>
<h2 id="features">Features</h2>
<ul>
<li>progressive loading</li>
<li>partial loading</li>
<li>fractional scaling</li>
<li>multiple pixel formats:
<ul>
<li>rgb8, bgr8, rgba8, bgra8, argb8, abgr8,<br /> rgbx8, bgrx8, xrgb8, xbgr8,<br /> g8, ga8, ag8,<br /> ycc8, ycck8, cmyk8.</li>
</ul></li>
</ul>
<h2 id="libjpeg.loadoptions_t-filename-read---image"><code>libjpeg.load(options_t | filename | read) -> image</code></h2>
<p>Read and decode a JPEG image. <code>options_t</code> is a table containing at least the data source and possibly other options.</p>
<h3 id="the-image-source">1. The image source:</h3>
<ul>
<li><code>path</code>: read data from a file.</li>
<li><code>string</code>: read data from a string.</li>
<li><code>cdata</code>, <code>size</code>: read data from a buffer of specified size.</li>
<li><code>stream</code>: read data from an opened <code>FILE *</code> stream.</li>
<li><code>read</code>: read data from a reader function of the form: <code>read() -> cdata, size | string | nil</code></li>
</ul>
<h3 id="decoding-and-conversion-options">2. Decoding and conversion options:</h3>
<ul>
<li><code>accept.<pixel_format>: true/false</code> specify one or more accepted pixel formats (see above).</li>
<li><code>accept.top_down</code>: true/false (default is true)</li>
<li><code>accept.bottom_up</code>: true/false</li>
<li><code>accept.padded</code>: true/false (default is false) - specify that the row stride should be a multiple of 4.</li>
<li><code>scale_num</code>, <code>scale_denom</code>: scale down the image by the fraction scale_num/scale_denom. Currently, the only supported scaling ratios are M/8 with all M from 1 to 16, or any reduced fraction thereof (such as 1/2, 3/4, etc.) Smaller scaling ratios permit significantly faster decoding since fewer pixels need be processed and a simpler IDCT method can be used.</li>
<li><code>dct_method</code>: 'accurate', 'fast', 'float' (default is 'accurate')</li>
<li><code>fancy_upsampling</code>: true/false (default is false); use a fancier upsampling method.</li>
<li><code>block_smoothing</code>: true/false (default is false); smooth out large pixels of early progression stages for progressive JPEGs.</li>
<li><code>partial_loading</code>: true/false (default is true); display broken images partially or break with an error.</li>
<li><code>header_only</code>: do not decode the image; return only the image header fields.</li>
<li><code>render_scan</code>: a function to be called as <code>render_scan(image, is_last_scan, scan_number)</code> for each progressive scan of a multi-scan JPEG. It can used to implement progressive display of images.
<ul>
<li>also called once for single-scan images.</li>
<li>also called on error, as <code>render_scan(nil, true, scan_number, error)</code>, where <code>scan_number</code> is the scan number that was supposed to be rendering next and <code>error</code> the error message.</li>
</ul></li>
<li><code>warning</code>: a function to be called as <code>warning(msg, level)</code> on non-fatal errors.</li>
</ul>
<blockquote>
<p><strong>NOTE</strong>: Not all conversions are possible with libjpeg-turbo, so always check the image's <code>format</code> field to get the actual format. Use <a href="bitmap.html">bitmap</a> to further convert the image if necessary.</p>
</blockquote>
<p>For more info on the decoding process and options read the <a href="http://sourceforge.net/p/libjpeg-turbo/code/HEAD/tree/trunk/libjpeg.txt">libjpeg-turbo doc</a>.</p>
<h3 id="the-return-value">3. The return value:</h3>
<p>The return value is a <a href="bitmap.html">bitmap</a> with extra fields:</p>
<ul>
<li><code>file</code>: a table describing the source file, with the following attributes:
<ul>
<li><code>w</code>, <code>h</code>, <code>format</code>, <code>progressive</code>, <code>jfif</code>, <code>adobe</code>.</li>
</ul></li>
<li><code>partial</code>: true if the image was found to be truncated and it was partially loaded.</li>
</ul>
<p>NOTE:</p>
<ul>
<li>the number of bits per channel in the output bitmap is always 8.</li>
<li>the bitmap fields are not present with the <code>header_only</code> option.</li>
<li>unknown JPEG formats are loaded but the <code>format</code> field is missing.</li>
</ul>
<h2 id="libjpeg.saveoptions_t---string-chunks_t-nil"><code>libjpeg.save(options_t) -> string | chunks_t | nil</code></h2>
<p>Save a <a href="bitmap.html">bitmap</a> as JPEG. <code>options_t</code> is a table containing at least the source bitmap and destination, and possibly other options.</p>
<h3 id="the-source-bitmap">1. The source bitmap:</h3>
<ul>
<li><code>bitmap</code>: a <a href="bitmap.html">bitmap</a> in an accepted format (see above).</li>
</ul>
<h3 id="the-output">2. The output:</h3>
<ul>
<li><code>path</code>: write data to a file.</li>
<li><code>stream</code>: write data to an opened <code>FILE *</code> stream.</li>
<li><code>chunks</code>: append data chunks to a list (which is also returned).</li>
<li><code>write</code>: write data to a sink of the form: <code>write(buf, size)</code></li>
<li><code>finish</code>: optional function to be called after all the data is written.</li>
</ul>
<p>If no output option is specified, the jpeg binary is returned as a Lua string.</p>
<h3 id="encoding-options">3. Encoding options:</h3>
<ul>
<li><code>format</code>: output format (see list of supported formats above).</li>
<li><code>quality</code>: 0..100 range. you know what that is.</li>
<li><code>progressive</code>: true/false (default is false). make it progressive.</li>
<li><code>dct_method</code>: 'accurate', 'fast', 'float' (default is 'accurate').</li>
<li><code>optimize_coding</code>: optimize huffmann tables.</li>
<li><code>smoothing</code>: 0..100 range. smoothing factor.</li>
<li><code>bufsize</code>: internal buffer size (default is 4096).</li>
</ul>
<h2 id="limitations">Limitations</h2>
<ul>
<li>no support for loading and saving huge images, i.e. working with a few scanlines at a time (easy).</li>
<li>jit is turned off because we can't call error() from a ffi callback called from C; and yet libjpeg says that we must not return control to C on errors, and the only way to do that is to call error().</li>
<li>the read callback cannot yield since it is called from C code. This means that reading data with coroutine-based socket schedulers is not an option. The workaround is to either bind the suspended I/O mode of libjpeg (easy), or to use threads and locking.</li>
</ul>
<hr />
<p>See also: <a href="nanojpeg.html">nanojpeg</a></p>
</section>
</div>
<div id="tab2_container" class="doc"></div>
</div>
</div>
<div class="container">
<footer>
<div id="disqus_thread"></div>
<div class="faint">[email protected] | <a href="http://unlicense.org/">public domain</a></div>
</footer>
</div>
</div>
<script type="text/x-mustache" id=info_tab_template>
<h3>Modules</h3>
<ul>
{{#module_array}}
<li>{{name}}</li>
{{/module_array}}
</ul>
</script>
</body>
</html>