source: project/release/3/imlib2/trunk/imlib2.html @ 10060

Last change on this file since 10060 was 10060, checked in by Kon Lovett, 13 years ago

Save.
File size: 16.6 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<!-- Generated by eggdoc Revision: 1.20  -->
3<html>
4<head>
5<title>Eggs Unlimited - imlib2</title><style type="text/css"> <!--
6      CODE {
7            color: #666666;
8          }
9/*   DT.definition EM { font-weight: bold; font-style: normal; } */
10
11     DT.definition { 
12                   background: #eee;
13                   color: black;
14                   padding: 0.2em 1em 0.2em 0.7em;
15                   margin-left: 0.2em;
16border: 1px solid #bbc;
17                   font-family: "Andale Mono", monospace;
18                   /* font-size: 1.2em; */
19                   
20                 }
21     DD {
22                   margin-top: 0.8em;
23                   margin-bottom: 0.8em;
24     }
25     DIV.subsection {
26                    border-top: 1px solid #448;
27                    padding-left: 1em;
28                    margin-bottom: 1.2em;
29     }
30     DIV.subsubsection {
31                    border-top: 1px dotted #99c;
32                    /* border-left: 1px solid #99c; */
33                    padding-left: 1em;
34                    margin-bottom: 1.2em;
35     }
36     DIV.subsubsubsection {
37                    border-top: 1px solid #ddf;
38                    padding-left: 1em;
39                    margin-bottom: 1.2em;
40     }
41
42         DIV.section {
43                 margin-bottom: 1.5em;
44         }
45         a:link {
46                 color: #336;
47         }
48         a:visited { color: #666; }
49         a:active  { color: #966; }
50         a:hover   { color: #669; }
51         body { margin: 0; padding: 0; background: #fff; color: #000; font: 9pt "Lucida Grande", "Verdana", sans-serif; }
52         H2 {
53                 background: #336;
54                 color: #fff;
55                 padding-top: 0.5em;
56                 padding-bottom: 0.5em;
57                 padding-left: 16px;
58                 margin: 0 0 1em 0;
59        }
60        UL LI {
61                list-style: none;
62        }
63        TT {
64                font-family: "Andale Mono", monospace;
65                /* font-size: 1.2em; */
66        }
67        H3 {
68                color: #113;
69                margin-bottom: 0.5em;
70        }
71        H4, H5, H6 {
72                color: #113;
73                margin-bottom: 1.0em;
74        }
75        H5 {
76                font-weight: normal;
77                font-style: italic;
78                font-size: 100%;
79                margin-top: 1.2em;
80        }
81        H6 {
82                font-weight: bold;
83                font-size: 85%;
84                margin-top: 1.2em;
85        }
86     DIV#eggheader {
87         text-align: center;
88                 float: right;
89                 margin-right: 2em;
90     }
91     DIV#header IMG {
92            /* display: block; margin-left: auto; margin-right: auto;  */
93            /* float: right; */
94            border: none;  /* firefox */
95     }
96     DIV#footer {
97                background: #bbd;
98                padding: 0.7em ;
99                border-top: 1px solid #cce;
100     }
101     DIV#footer hr {
102                display: none;
103     }
104     DIV#footer a {
105                float: left;
106     }
107     DIV#revision-history {
108         float: right;
109     }
110     
111     DIV#body {
112                 margin: 1em 1em 1em 16px;
113         }
114
115     DIV#examples PRE {
116       background: #eef;
117       padding: 0.1em;
118       border: 1px solid #aac;
119     }
120     PRE#license, DIV#examples PRE {
121       padding: 0.5em;
122     }
123     DIV#examples PRE {
124       /* font-size: 85%; */
125     }
126     PRE { font-family: "Andale Mono", monospace; }
127     TABLE {
128       background: #eef;
129       padding: 0.2em;
130       border: 1px solid #aac;
131       border-collapse: collapse;
132       width: 100%;
133     }
134     TABLE.symbol-table TD.symbol {
135          width: 15em;
136          font-family: "Andale Mono", monospace;
137          /* font-size: 1.2em; */
138     }
139     TH {
140       text-align: left;
141       border-bottom: 1px solid #aac;
142       padding: 0.25em 0.5em 0.25em 0.5em;
143     } 
144     TD { padding: 0.25em 0.5em 0.25em 0.5em; }
145     --></style></head>
146<body>
147<div id="header">
148<h2>imlib2</h2>
149<div id="eggheader"><a href="index.html">
150<img src="egg.jpg" alt="[Picture of an egg]" /></a></div></div>
151<div id="body">
152<div class="section">
153<h3>Description</h3>
154<p>Chicken bindings for the <a href="http://enlightenment.sourceforge.net/doxy/imlib2/index.html">imlib2</a> image library.</p></div>
155<div class="section">
156<h3>Author</h3><a href="mailto:peter.bex@xs4all.nl">Peter Bex</a></div>
157<div class="section">
158<h3>Version</h3>
159<ul>
160<li>0.6 Fix for wrong variable names.</li>
161<li>0.5 Fix define/clone bug; thanks to Graham Fawcett</li>
162<li>0.4 Fix finalizer bug; set correct context before freeing</li>
163<li>0.3 Set GC finalizers on all functions that create new imlib objects and allow linking against imlib2 that was compiled without X and converted documentation to eggdoc.</li>
164<li>0.2 <code>imlib:alpha-set!</code> wasn't exported</li>
165<li>0.1 beta release</li></ul></div>
166<div class="section">
167<h3>Requires</h3>
168<ul>
169<li><a href="syntax-case.html">syntax-case</a></li></ul></div>
170<div class="section">
171<h3>Usage</h3><tt>(require-extension imlib2)</tt></div>
172<div class="section">
173<h3>Download</h3><a href="imlib2.egg">imlib2.egg</a></div>
174<div class="section">
175<h3>Documentation</h3>
176<p>Note: Not all imlib functionality is provided by this egg yet!</p>
177<div class="subsection">
178<h4>Image creation, destruction and friends</h4>
179<dt class="definition"><strong>procedure:</strong> (imlib:create width height)</dt>
180<dd>Returns a new <code>imlib:image</code> object which describes a transparent image of the given size.</dd>
181<dt class="definition"><strong>procedure:</strong> (imlib:image? img)</dt>
182<dd>Determine if the given <code>img</code> object is an imlib image.</dd>
183<dt class="definition"><strong>procedure:</strong> (imlib:destroy img)</dt>
184<dd>Destroy the given image.</dd>
185<dt class="definition"><strong>procedure:</strong> (imlib:clone img)</dt>
186<dd>Create a fresh copy of the image object <code>img</code></dd>
187<dt class="definition"><strong>procedure:</strong> (imlib:load filename)</dt>
188<dd>Returns a new <code>imlib:image</code> object which describes the image stored in the file <code>filename</code>.  This automatically uses the correct loader, as determined by Imlib2 on the basis of the file's extension.</dd>
189<dt class="definition"><strong>procedure:</strong> (imlib:save img filename)</dt>
190<dd>Store the imlib image object described by <code>img</code> in the file <code>filename</code>.  The right loader is automatically selected by Imlib2 if you haven't set it explicitly with <code>imlib:format-set!</code>.</dd></div>
191<div class="subsection">
192<h4>Image properties</h4>
193<dt class="definition"><strong>procedure:</strong> (imlib:format img)</dt>
194<dd>Request the currently set format for the image, or <code>#f</code> if no format has been associated with it yet.</dd>
195<dt class="definition"><strong>procedure:</strong> (imlib:format-set! img format)</dt>
196<dd>Explicitly set the file format on the image for subsequent calls to <code>imlib:save</code>.  The <code>format</code> argument is passed to the loaders in the same way a file extension would be.</dd>
197<dt class="definition"><strong>procedure:</strong> (imlib:width img)</dt>
198<dd>Returns the width of the supplied image, in pixels.</dd>
199<dt class="definition"><strong>procedure:</strong> (imlib:height img)</dt>
200<dd>Returns the height of the supplied image, in pixels.</dd>
201<dt class="definition"><strong>procedure:</strong> (imlib:filename img)</dt>
202<dd>Returns the original filename for the image, if it was loaded from a file.  Otherwise it returns <code>#f</code>.</dd>
203<dt class="definition"><strong>procedure:</strong> (imlib:alpha? img)</dt>
204<dd>Does the image have an alpha layer?</dd>
205<dt class="definition"><strong>procedure:</strong> (imlib:alpha-set! img value)</dt>
206<dd>Enable or disable alpha layer support for the image.</dd>
207<dt class="definition"><strong>procedure:</strong> (imlib:track-changes-on-disk img)</dt>
208<dd>From now on, track changes on disk to the file that is associated with <code>img</code>. By default, all images are cached by imlib2 in such a way that closing and reopening it just pulls it from cache instead of really loading it.  Unfortunately, there's no way to request the status of this option or disable it.</dd></div>
209<div class="subsection">
210<h4>Image manipulation operations</h4>
211<div class="subsubsection">
212<h5>Orientation</h5>
213<dt class="definition"><strong>procedure:</strong> (imlib:flip-horizontal img)</dt>
214<dd>Create a new, horizontally flipped, copy of <code>img</code>.</dd>
215<dt class="definition"><strong>procedure:</strong> (imlib:flip-horizontal! img)</dt>
216<dd>Destructively flip <code>img</code> horizontally.</dd>
217<dt class="definition"><strong>procedure:</strong> (imlib:flip-vertical img)</dt>
218<dd>Create a new, vertically flipped, copy of <code>img</code>.</dd>
219<dt class="definition"><strong>procedure:</strong> (imlib:flip-vertical! img)</dt>
220<dd>Destructively flip <code>img</code> vertically.</dd>
221<dt class="definition"><strong>procedure:</strong> (imlib:flip-diagonal img)</dt>
222<dd>Create a new, diagonally flipped, copy of <code>img</code>.  This works like transposing a matrix.</dd>
223<dt class="definition"><strong>procedure:</strong> (imlib:flip-diagonal! img)</dt>
224<dd>Destructively flip <code>img</code> diagonally.</dd>
225<dt class="definition"><strong>procedure:</strong> (imlib:orientate img orientation)</dt>
226<dd>Create a new, orientated copy of <code>img</code>. According to imlib2 documentation, this function rotates the image by 90 degrees <code>orientation</code> times.  However, the function accepts values between 0 and 7, inclusive.  What values 4-7 do, I'm not really sure of.  They appear to rotate the image <code>(mod orientation 3)</code> times 90 degrees, but flip it as well.</dd></div>
227<div class="subsubsection">
228<h5>Texture/retouching functions</h5>
229<dt class="definition"><strong>procedure:</strong> (imlib:sharpen img radius)</dt>
230<dd>Create a new, sharpened copy of <code>img</code>. The <code>radius</code> argument is an integer number indicating the degree of sharpening that has to take place.  I am not sure what a negative value means, but it is allowed.</dd>
231<dt class="definition"><strong>procedure:</strong> (imlib:sharpen! img radius)</dt>
232<dd>Destructively sharpen an image.</dd>
233<dt class="definition"><strong>procedure:</strong> (imlib:blur img radius)</dt>
234<dd>Create a new, blurred copy of <code>img</code>. The <code>radius</code> argument is a positive integer indicating the blur matrix radius, so 0 has no effect.</dd>
235<dt class="definition"><strong>procedure:</strong> (imlib:blur! img radius)</dt>
236<dd>Destructively blur an image.</dd>
237<dt class="definition"><strong>procedure:</strong> (imlib:tile img)</dt>
238<dd>Create a new copy of <code>img</code> adjusted in such a way around the edges, such that it is suitable for use in repeating (&quot;tiled&quot;) patterns on all sides.</dd>
239<dt class="definition"><strong>procedure:</strong> (imlib:tile! img)</dt>
240<dd>Destructively tile an image.</dd>
241<dt class="definition"><strong>procedure:</strong> (imlib:tile-horizontal img)</dt>
242<dd>Create a new copy of <code>img</code> adjusted on the left and right edges so it can be used for horizontally repeating patterns.</dd>
243<dt class="definition"><strong>procedure:</strong> (imlib:tile-horizontal! img)</dt>
244<dd>Destructively tile an image horizontally.</dd>
245<dt class="definition"><strong>procedure:</strong> (imlib:tile-vertical img)</dt>
246<dd>Create a new copy of <code>img</code> adjusted on the top and bottom edges so it can be used for vertically repeating patterns.</dd>
247<dt class="definition"><strong>procedure:</strong> (imlib:tile-vertical! img)</dt>
248<dd>Destructively tile an image vertically.</dd>
249<dt class="definition"><strong>procedure:</strong> (imlib:crop img x y width height)</dt>
250<dd>Create a new, cropped copy of <code>img</code>.  The <code>x</code> and <code>y</code> parameters indicate the upper left pixel of the new image.  The <code>width</code> and <code>height</code> parameters indicate the size of the new image.  Returns <code>#f</code> on failure. <strong>Note: This function will return an image of the requested size, but with undefined contents if you pass it arguments that lie outside the image!  I am still unsure if this is a bug or feature.</strong></dd>
251<dt class="definition"><strong>procedure:</strong> (imlib:scale img width height)</dt>
252<dd>Create a new, scaled copy of the image.</dd>
253<dt class="definition"><strong>procedure:</strong> (imlib:crop&amp;scale img src-x src-y src-width src-height dest-width dest-height)</dt>
254<dd>Create a new, cropped <em>and</em> scaled copy of <code>img</code>.  The arguments <code>src-x</code>, <code>src-y</code>, <code>src-width</code> and <code>src-height</code> indicate cropping dimensions as per <code>imlib:crop</code>, in the original image. The <code>dest-width</code> and <code>dest-height</code> arguments indicate the new image's width and height.</dd></div></div>
255<div class="subsection">
256<h4>Pixel query functions</h4>
257<dt class="definition"><strong>procedure:</strong> (imlib:pixel/rgba img x y)</dt>
258<dd>Returns the RGBA (red, green, blue, alpha) color values for the image at the specified pixel coordinate as 4 values.</dd>
259<dt class="definition"><strong>procedure:</strong> (imlib:pixel/hsva img x y)</dt>
260<dd>Returns the HSVA (hue, saturation, value, alpha) color values for the image at the specified pixel coordinate as 4 values.</dd>
261<dt class="definition"><strong>procedure:</strong> (imlib:pixel/hlsa img x y)</dt>
262<dd>Returns the HLSA (hue, lightness, saturation, alpha) color values for the image at the specified pixel coordinate as 4 values.</dd>
263<dt class="definition"><strong>procedure:</strong> (imlib:pixel/cmya img x y)</dt>
264<dd>Returns the CMYA (cyan, magenta, yellow, alpha) color values for the image at the specified pixel coordinate as 4 values.</dd></div>
265<div class="subsection">
266<h4>Color specifiers</h4>
267<p>Note: This could use some more work.  Perhaps the functions fromthe previous section should return values of these types instead.</p>
268<dt class="definition"><strong>procedure:</strong> (imlib:color? color)</dt>
269<dd>Is the specified object an imlib color specifier?</dd>
270<dt class="definition"><strong>procedure:</strong> (imlib:color/rgba r g b a)</dt>
271<dd>Create a color specifier for the given RGBA values.</dd>
272<dt class="definition"><strong>procedure:</strong> (imlib:color/hsva h s v a)</dt>
273<dd>Create a color specifier for the given HSVA values.</dd>
274<dt class="definition"><strong>procedure:</strong> (imlib:color/hlsa h l s a)</dt>
275<dd>Create a color specifier for the given HLSA values.</dd>
276<dt class="definition"><strong>procedure:</strong> (imlib:color/cmya c m y a)</dt>
277<dd>Create a color specifier for the given CMYA values.</dd></div>
278<div class="subsection">
279<h4>Drawing functions</h4>
280<dt class="definition"><strong>procedure:</strong> (imlib:draw-pixel img color x y)</dt>
281<dd>Draw a pixel in the given image on the given coordinates with the given color specifier.</dd>
282<dt class="definition"><strong>procedure:</strong> (imlib:draw-line img color x1 y1 x2 y2)</dt>
283<dd>Draw a line in the image from the coordinates (<code>x1</code>,<code>y1</code>) to (<code>x2</code>,<code>y2</code>.</dd>
284<dt class="definition"><strong>procedure:</strong> (imlib:draw-rectangle img color x y width height)</dt>
285<dd>Draw a one-pixel wide outline of a rectangle with the given color.  The <code>x</code> and <code>y</code> coordinates are of the upper left corner of the rectangle.</dd>
286<dt class="definition"><strong>procedure:</strong> (imlib:fill-rectangle img color x y width height)</dt>
287<dd>Same as <code>imlib:draw-rectangle</code>, but filled in.</dd></div></div>
288<div class="section">
289<h3>License</h3>
290<pre id="license">Copyright (c) 2005, 2006, Peter Bex (peter.bex@xs4all.nl)
291All rights reserved.
292
293Redistribution and use in source and binary forms, with or without
294modification, are permitted provided that the following conditions
295are met:
2961. Redistributions of source code must retain the above copyright
297   notice, this list of conditions and the following disclaimer.
2982. Redistributions in binary form must reproduce the above copyright
299   notice, this list of conditions and the following disclaimer in the
300   documentation and/or other materials provided with the distribution.
3013. Neither the name of Peter Bex nor the names of any contributors may
302   be used to endorse or promote products derived from this software
303   without specific prior written permission.
304
305THIS SOFTWARE IS PROVIDED BY PETER BEX AND CONTRIBUTORS ``AS IS'' AND ANY
306EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
307WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
308DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE
309FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
310DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
311SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
312CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
313LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
314OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
315SUCH DAMAGE.</pre></div></div>
316<div id="footer">
317<hr /><a href="index.html">&lt; Egg index</a>
318<div id="revision-history">$Revision$ $Date$</div>&nbsp;</div></body></html>
Note: See TracBrowser for help on using the repository browser.