source: project/wiki/eggref/4/imlib2 @ 13306

Last change on this file since 13306 was 13306, checked in by felix winkelmann, 12 years ago

added xlib page and removed download links

File size: 10.0 KB
Line 
1[[tags: egg]]
2
3== epeg
4
5[[toc:]]
6
7=== Description
8
9Chicken bindings for the [[http://docs.enlightenment.org/api/imlib2/html|imlib2]] image library.
10
11=== Author
12
13[[Peter Bex]]
14
15=== Requirements
16
17None
18
19=== Documentation
20
21Note that currently not all imlib2 functionality has been added to this egg.
22
23==== Image creation, destruction and friends
24
25<procedure>(image-create width height) => image</procedure>
26
27Returns a new imlib2 image object which represents a transparent image
28of the given size.
29
30<procedure>(image? img) => boolean</procedure>
31
32Determine if {{img}} is an imlib image.
33
34<procedure>(image-destroy img)</procedure>
35
36Destroy the given image object.
37
38<procedure>(image-clone img) => image</procedure>
39
40Create a fresh copy of the image object {{img}}.
41
42<procedure>(image-load filename) => image</procedure>
43
44Returns a new imlib image object which represents the image stored in
45the file {{filename}}.  This automatically uses the correct loader, as
46determined by Imlib2 on the basis of the file's extension.
47
48<procedure>(image-save img filename)</procedure>
49
50Store the imlib image object represented by {{img}} in the file
51{{filename}}.  The right loader is automatically selected by Imlib2 if
52you haven't set it explicitly with {{image-format-set!}}.
53
54==== Image properties
55
56<procedure>(image-format img) => string</procedure>
57
58Request the currently set format for the image, or {{#f}} if no format
59has been associated with it yet.
60
61<procedure>(image-format-set! img format)</procedure>
62
63Explicitly set the file format on the image for subsequent calls to
64{{image-save}}.  The {{format}} argument is passed to the loaders in
65the same way a file extension would be.
66
67<procedure>(image-width img) => integer</procedure>
68
69Returns the width of the supplied image, in pixels."
70
71<procedure>(image-height img) => integer</procedure>
72
73Returns the height of the supplied image, in pixels.
74
75<procedure>(image-filename img) => string</procedure>
76
77Returns the original filename for the image, if it
78was loaded from a file.  Otherwise it returns {{#f}}.
79
80<procedure>(image-alpha? img) => boolean</procedure>
81
82Does the image have an alpha layer?
83
84<procedure>(image-alpha-set! img value)</procedure>
85
86Enable or disable alpha layer support for the image.
87
88<procedure>(image-track-changes-on-disk img)</procedure>
89
90From now on, track changes on disk to the file that is associated with
91{{img}}. By default, all images are cached by imlib2 in such a way
92that closing and reopening it just pulls it from cache instead of
93really loading it.  Unfortunately, there's no way to request the
94status of this option or disable it.
95
96==== Image manipulation operations
97
98All these operations create a copy of the image. This can eat a lot of
99memory if you're not careful. Use the methods ending with a bang if
100you just want to destructively update an existing image.
101
102===== Orientation
103
104<procedure>(image-flip-horizontal img) => image</procedure>
105<procedure>(image-flip-horizontal! img) => image</procedure>
106
107Horizontally flip {{img}}.
108     
109<procedure>(image-flip-vertical img) => image</procedure>
110<procedure>(image-flip-vertical! img) => image</procedure>
111
112Vertically flip {{img}}.
113     
114<procedure>(image-flip-diagonal img) => image</procedure>
115<procedure>(image-flip-diagonal! img) => image</procedure>
116
117Diagonally flip {{img}}.  This works like transposing a matrix.
118
119<procedure>(image-orientate img orientation) => image</procedure>
120<procedure>(image-orientate! img orientation) => image</procedure>
121
122Orientate {{img}}. According to imlib2 documentation, this procedure
123rotates the image by 90 degrees {{orientation}} times.  However, the
124procedure accepts values between 0 and 7, inclusive.  What values 4-7
125do, I'm not really sure of.  They appear to rotate the image {{(mod
126orientation 3)}} times 90 degrees, but flip it as well.
127
128===== Texture/retouching procedures
129
130<procedure>(image-sharpen img radius) => image</procedure>
131<procedure>(image-sharpen! img radius) => image</procedure>
132
133Sharpen {{img}}. The {{radius}} argument is an integer number
134indicating the degree of sharpening that has to take place. I am not
135sure what a negative value means, but it is allowed.
136
137<procedure>(image-blur img radius) => image</procedure>
138<procedure>(image-blur! img radius) => image</procedure>
139
140Blur {{img}}. The {{radius}} argument is a positive integer indicating
141the blur matrix radius, so 0 has no effect.
142
143<procedure>(image-tile img) => image</procedure>
144<procedure>(image-tile! img) => image</procedure>
145<procedure>(image-tile-horizontal img) => image</procedure>
146<procedure>(image-tile-horizontal! img) => image</procedure>
147<procedure>(image-tile-vertical img) => image</procedure>
148<procedure>(image-tile-vertical! img) => image</procedure>
149
150Adjust {{img}} in such a way around the edges, such that it is
151suitable for use in repeating ("tiled") patterns on all sides, only
152horizontally or only vertically.
153
154<procedure>(image-crop img x y width height) => image</procedure>
155<procedure>(image-crop! img x y width height) => image</procedure>
156
157Crop {{img}}.  The {{x}} and {{y}} parameters indicate the upper left
158pixel of the new image.  The {{width}} and {{height}} parameters
159indicate the size of the new image.  Returns {{#f}} on failure.
160
161'''Note''': This procedure will return an image of the requested size,
162but with undefined contents if you pass it arguments that lie outside
163the image!  I am still unsure if this is a bug or feature.
164
165<procedure>(image-scale img width height)</procedure>
166
167Create a new, scaled copy of the image.
168
169<procedure>(image-crop&scale img src-x src-y src-width src-height dest-width dest-height)</procedure>
170
171Create a new, cropped ''and'' scaled copy of {{img}}.  The arguments
172{{src-x}}, {{src-y}}, {{src-width}} and {{src-height}} indicate
173cropping dimensions as per {{image-crop}}, in the original image.  The
174{{dest-width}} and {{dest-height}} arguments indicate the new image's
175width and height.
176
177==== Pixel query procedures
178
179<procedure>(image-pixel/rgba img x y) => integer integer integer integer</procedure>
180
181Returns the RGBA (red, green, blue, alpha) color values for the image
182at the specified pixel coordinate as 4 values.
183
184<procedure>(image-pixel/hsva img x y) => integer integer integer integer</procedure>
185
186Returns the HSVA (hue, saturation, value, alpha) color values for the
187image at the specified pixel coordinate as 4 values.
188
189<procedure>(image-pixel/hlsa img x y) => integer integer integer integer</procedure>
190
191Returns the HLSA (hue, lightness, saturation, alpha) color values for
192the image at the specified pixel coordinate as 4 values.
193
194<procedure>(image-pixel/cmya img x y) => integer integer integer integer</procedure>
195
196Returns the CMYA (cyan, magenta, yellow, alpha) color values for the
197image at the specified pixel coordinate as 4 values.
198
199==== Color specifiers
200
201'''Note:''' This could use some more work.  Perhaps the procedures
202from the previous section should return values of these types instead.
203
204<procedure>(color? color) => boolean</procedure>
205
206Is the specified object an imlib color specifier?
207
208<procedure>(color/rgba r g b a) => color</procedure>
209
210Create a color specifier for the given RGBA values.
211
212<procedure>(color/hsva h s v a) => color</procedure>
213
214Create a color specifier for the given HSVA values.
215
216<procedure>(color/hlsa h l s a) => color</procedure>
217
218Create a color specifier for the given HLSA values.
219
220<procedure>(color/cmya c m y a) => color</procedure>
221
222Create a color specifier for the given CMYA values.
223
224==== Drawing procedures
225
226The following procedures all destructively update the image object.
227
228<procedure>(image-draw-pixel img color x y)</procedure>
229
230Draw a pixel in the given image on the given coordinates with the
231given color specifier.
232
233<procedure>(image-draw-line img color x1 y1 x2 y2)</procedure>
234
235Draw a line in the image from the coordinates ({{x1}},{{y1}}) to
236({{x2}},{{y2}}).
237
238<procedure>(image-draw-rectangle img color x y width height)</procedure>
239
240Draw a one-pixel wide outline of a rectangle with the given color.
241The {{x}} and {{y}} coordinates are of the upper left corner of the
242rectangle.
243
244<procedure>(image-fill-rectangle img color x y width height)</procedure>
245
246Same as {{image-draw-rectangle}}, but filled in.
247
248=== Changelog
249
250* 0.7 Port to Chicken 4, procedure renaming (removal of prefix), switch to wiki for documentation
251* 0.6 Fix for wrong variable names.
252* 0.5 Fix define/clone bug; thanks to Graham Fawcett
253* 0.4 Fix finalizer bug; set correct context before freeing
254* 0.3 Set GC finalizers on all procedures that create new imlib objects and allow linking against imlib2 that was compiled without X and converted documentation to eggdoc.
255* 0.2 {{imlib:alpha-set!}} wasn't exported
256* 0.1 Beta release
257
258=== License
259
260  Copyright (c) 2005-2008, Peter Bex
261  All rights reserved.
262 
263  Redistribution and use in source and binary forms, with or without
264  modification, are permitted provided that the following conditions are
265  met:
266 
267  Redistributions of source code must retain the above copyright
268  notice, this list of conditions and the following disclaimer.
269 
270  Redistributions in binary form must reproduce the above copyright
271  notice, this list of conditions and the following disclaimer in the
272  documentation and/or other materials provided with the distribution.
273 
274  Neither the name of the author nor the names of its contributors may
275  be used to endorse or promote products derived from this software
276  without specific prior written permission.
277 
278  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
279  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
280  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
281  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
282  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
283  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
284  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
285  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
286  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
287  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
288  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
289  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.