-
Notifications
You must be signed in to change notification settings - Fork 1
/
libpng.html
156 lines (149 loc) · 7.19 KB
/
libpng.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
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<title> libpng - PNG reader </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 = 'libpng'
var PROJECT = 'libpng'
//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> libpng </h1>
<h2> PNG reader </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/libpng" class="btn btn-rightside btn-github"><span class="icon"></span>View on GitHub</a>
</td></tr><tr><td>
<a href="https://github.com/luapower/libpng/tarball/master" class="btn btn-rightside">Download as .tar.gz</a>
</td></tr><tr><td>
<a href="https://github.com/luapower/libpng/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/libpng/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-libpng" style="background-image: url('bg/libpng.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="note-work-in-progress-version-1.0-coming-soon">NOTE: work-in-progress (version 1.0 coming soon)</h2>
<h2 id="local-libpng-requirelibpng"><code>local libpng = require'libpng'</code></h2>
<p>A ffi binding of the ubiquitous <a href="http://www.libpng.org/pub/png/libpng.html">libpng</a>.</p>
<h2 id="libpng.loadt---image"><code>libpng.load(t) -> image</code></h2>
<p>Read and decode a PNG image.</p>
<ul>
<li><code>t</code> is a table specifying:
<ul>
<li>where to read the data from (one of the following):
<ul>
<li><code>path</code>: read data from a file given its filename</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 form:</li>
<li><code>read(needed_size) -> cdata, size | string | nil</code>
<ul>
<li><code>needed_size</code> is informative, the function can return however many bytes it wants, as long as it returns at least 1 byte.</li>
</ul></li>
</ul></li>
<li>loading options:
<ul>
<li><code>accept</code>: if present, it is a table specifying conversion options. libpng implements many of the pixel conversions itself, while other conversions are supported through [bmpconv bmpconv.convert_best()]. If no <code>accept</code> option is given, the image is returned in a normalize 8 bit per channel, top down, palette expanded, 'g', 'rgb', 'rgba' or 'ga' format.</li>
<li><code>[pixel_format] = true</code> - specify one or more accepted pixel formats (they are all implicitly 8 bit per channel since that is the only supported bit depth):
<ul>
<li>'rgb', 'bgr', 'rgba', 'bgra', 'argb', 'abgr', 'g', 'ga', 'ag'.
<ul>
<li>if no pixel format is specified, resulted bit depth will not necessarily be 8 since no conversion will take place.</li>
</ul></li>
</ul></li>
<li><code>[orientation] = true</code> - specify one or more accepted orientations:
<ul>
<li>'top_down', 'bottom_up' (default is 'top_down')</li>
</ul></li>
<li><code>padded</code>: true/false (default is false) - specify that the row stride should be a multiple of 4</li>
<li><code>header_only</code>: do not decompress the image; return only the image header fields.</li>
<li><code>sparkle</code>: true/false (default is false) - alternative render mode for interlaced images.</li>
</ul></li>
<li>callbacks:
<ul>
<li><code>warning</code>: a function to be called as <code>warning(msg)</code> on non-fatal errors.</li>
<li><code>render_scan</code>: a function to be called as <code>render_scan(image, is_last_scan, scan_number)</code> for each pass of an interlaced PNG. It can be used to implement progressive display of images.</li>
<li>also called once for non-interlaced 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>
</ul></li>
</ul>
<p>For more info on decoding process and options, read the <a href="http://www.libpng.org/pub/png/libpng-1.2.5-manual.html">libpng doc</a> (have coffee/ibuprofen ready).</p>
<p>The returned image object is a table with the fields: * <code>pixel</code>, <code>orientation</code>, <code>stride</code>, <code>data</code>, <code>size</code>, <code>w</code>, <code>h</code>: image format and dimensions and pixel data. * <code>file.pixel</code>, <code>file.paletted</code>, <code>file.bit_depth</code>, <code>file.interlaced</code>, <code>file.w</code>, <code>file.h</code>: format of the original image before conversion.</p>
<h2 id="help-needed">Help needed</h2>
<ul>
<li>encoding API</li>
<li>jit is turned off because we can't call error() from a ffi callback called from C; and yet we must not return control to C on errors. is there a way around it?</li>
<li>the read callback cannot yield since it is called from C code. this means coroutine-based socket schedulers are out, so much for progressive loading. is there a way around it?</li>
</ul>
</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>