asb / lua-imlib2

A complete binding to the Imlib2 image manipulation library

This URL has Read+Write access

lua-imlib2 / DOCUMENTATION.mkd
raw normal view history
b76980b8 » asb 2008-07-27 separate API documentation ... 1 # `imlib2.color`
2 Represent colors in rgba format. Each instance of imlib2.color has the
3 modifiable fields red, green, blue and alpha. An error will be raised on an
4 attempt to set them to a value outside of the range `0 <= x <= 255`.
5 Non-integer values will be truncated.
6
7 ## `imlib2.color.new(red, green, blue[, alpha])`
8 Creates a new color. An error will be raised unless red, green, blue and
9 alpha are in the range `0 <= x <= 255`.
10
11 ## `col.red`, `col.green`, `col.blue`, `col.alpha`
12 Each instance of `imlib2.color` has integer fields `red`, `green`, `blue`,
13 and `alpha` which can be read and modified. An exception is raised if you try
14 to set the value outside the range `0 <= x <= 255`.
15
16 # `imlib2.border`
17 Represents a border. Contains left, top, right, bottom values as mutable
18 fields. A border is the area at the edge of an image that does not scale when
19 the rest of the image is resized - the borders remain constant in size.
20
21 ## `imlib2.border.new(left, top, right, bottom)`
22 Creates a new border. `left`, `top`, `right` and `bottom` are the size of each
23 side of the border in pixels.
24
25 ## `bd.left`, `bd.top`, `bd.right`, `bd.bottom`
26 Each instance of `imlib2.border` has these mutable fields.
27
28 # `imlib2.gradient`
29 Consists of colours and the offsets at which they occur.
30
31 ## `imlib2.gradient.new()`
32 Creates a new gradient. Use `grad:add_color()` to add colors to it.
33
34 ## `grad:add_color(offset, color)`
35 Add an `imlib2.color` instance at the given `offset`. `offset` is the distance
36 from the previous color in pixels. It has no meaning for the first color
37 added.
38
39 # `imlib2.polygon`
40 Represents a polygon object. Points are drawn in the order in which they are
41 added.
42
43 ## `imlib2.polygon.new() `
44 Create a new polygon. Add points using `poly:add_point()`.
45
46 ## `poly:add_point(x, y)`
47 Add point (x,y) to the polygon. `x` is the x coordinate in pixels, and `y` is
48 is the y coordinate in pixels.
49
50 ## `poly:get_bounds()`
51 Returns the four points of the rectangular bounding area for the polygon.
52
53 Returns `x1`, `y1` `x2`, `y2`:
54
55 * `x1`: x coordinate of the upper left corner
56 * `y1`: y coordinate of the upper left corner
57 * `x2`: x coordinate of the upper right corner
58 * `y2`: y coordinate of the lower right corner
59
60 ## `poly:contains_point(x, y)`
61 Returns true if the polygon contains point (x,y).
62
63 # `imlib2.font`
64 Instances represent a loaded font. Provides static methods for querying and
65 modifying the font paths used by imlib2.
66
67 ## `imlib2.font.load(name)`
68 Load the given font from the current font path. `name` is a font path, e.g.
69 "Vera/10". It returns a font object for a given font name, nil plus an error
70 message if no such font can be found on the path.
71
72 ## `imlib2.font.add_path(path)`
73 Add the given `path` to the list of paths Imlib2 searches when loading a font.
74
75 ## `imlib2.font.remove_path(path)`
76 Remove the given `path` from Imlib2's font path list.
77
78 ## `imlib2.font.list_paths()`
79 Returns a table containing all the font paths Imlib2 will search when asked to
80 load a font.
81
82 ## `imlib2.font.list_fonts()`
83 Returns an array of all the font names Imlib2 can find on its font path.
84
85 ## `imlib2.font.get_cache_size()`
86 Returns the font cache size in bytes.
87
88 ## `imlib2.font.set_cache_size()`
89 Sets the font cache size in bytes. Whenever you set the font cache size,
90 Imlib2 will flush fonts from the cache until the memory used by fonts is
91 less than or equal to the font cache size. Setting the size to 0 frees all
92 speculatively cached fonts.
93
94 ## `imlib2.font.set_direction(dir[, angle])`
95 Sets the direction that text will be drawn at. Accepts 90 degree
96 orientations, or an arbitrary angle. Raises an error for invalid direciton
97 names. Takes parameters:
98
99 * `dir` can be `"right"`, `"left"`, `"down"`, `"up"` or `"angle"` (in which
100 case parameter `angle` must be given)
101 * `angle` given in radians. Only needed if `direction` was `"angle"`.
102
103 ## `imlib2.font.get_direction()`
104 Gives the direction that text is set to be drawn at. Returns one of the
105 strings `"right"`, `"left"`, `"down"`, `"up"` or `"angle"`. If `"angle"` is
106 returned, then the angle in radians is given as the second return value.
107
108
109 ## `fnt:get_size(str)`
110 Get the width and height of the given string when drawn with `fnt`. Returns
111 the width and height in pixels.
112
113 ## `fnt:get_advance(str)`
114 Get the horizontal and vertical advance of the given string when drawn with
115 `fnt`. The horizontal and vertical advance are the number of pixels away the
116 next string would need to be placed at. The advances are not adjusted for
117 rotation, and are calculated as if the text was drawn horizontally from left
118 to right.
119
120 Returns the horizontal and vertical advance in pixels.
121
122 ## `fnt:get_inset(str)`
123 The inset in pixels of the first character of the given string.
124
125 ## `fnt:get_ascent()`
126 Get the font's ascent in pixels.
127
128 ## `fnt:get_maximum_ascent()`
129 Get the font's maximum ascent in pixels.
130
131 ## `fnt:get_descent()`
132 Get the font's descent in pixels.
133
134 ## `fnt:get_maximum_descent()`
135 Get the font's maximum descent in pixels.
136
137 # `imlib2.image`
138 Methods for image loading, saving and manipulation.
139
140 ## `image.new(width, height)`
141 Create a new image. `width` and `height` are given in pixels.
142
143 ## `image.load(path)`
144 Loads the image at the given path. Imlib2 searches its loader modules until it
145 finds one that can decode the file at the given path. The loader modules
146 available to you (and hence the range of filetypes you are able to load) will
147 depend on the options used when building the Imlib2 shared library. Loaders
148 will not decode image data until it is needed (provided this is feasible for
149 the given file format). This means it is perfectly sensible to load many files
150 in order to query their header information such as width and height. If the
151 image is present in Imlib2's cache, it won't check if the file has changed and
152 will instead just return that cached version of the image.
153
154 Returns the loaded image or else nil plus an error message
155
156 ## `img:free()`
157 Frees the image. This does not evict the image from Imlib2's cache.
158
159 ## `img:clone()`
160 Obtain a clone of the image.
161
162 ## `img:get_width()`
163 Get the width of the image in pixels.
164
165 ## `img:get_height()`
166 Get the height of the image in pixels.
167
168 ## `img:get_filename()`
169 Returns the current image filename.
170
171 ## `img:get_format()`
172 Get the current image format.
173
174 ## `img:set_format(format)`
175 Sets the image format to the given string. No check is made to ensure that the
176 Imlib2 shared library can save in this format. If it can not, `img:save()`
177 will later fail.
178
179 ## `img:has_alpha()`
180 Gives a boolean value indicating whether the image has an alpha channel.
181
182 ## `img:set_alpha(bool)`
183 Enable or disable the image's alpha channel based on the given boolean.
184
185 ## `img:get_border()`
186 Get the imlib2.border object for `img`.
187
188 ## `img:set_border(border)`
189 Sets the image border to the given `imlib2.border` object.
190
191 ## `img:get_pixel(x, y)`
192 Gives the color of the pixel at the given (x,y) coordinates. The origin -
193 (0,0) is at the top left.
194
195 Return an instance of imlib2.color matching the color at the given
196 coordinates.
197
198 ## `img:crop(x, y, width, height)`
199 Crops the image to the given rectangle.
200
201 Takes the parameters:
202
203 * `x` the x coordinate of the top left corner
204 * `y` the y coordinate of the top left corner
205 * `width` the width of the rectangle
206 * `height` the height of the rectangle
207
208 ## `img:crop_and_scale(source_x, source_y, source_h, source_w, dest_w, dest_h)`
209 Crops the image to the given rectangle and also scales it. The image will be
210 scaled to the given destination width and height.
211
212 Takes the parameters:
213
214 * `source_x` the x coordinate of the top left corner of the source rectangle
215 * `source_y` the y coordinate of the top left corner of the source rectangle
216 * `source_h` the height of the source rectangle
217 * `source_w` the width of the source rectangle
218 * `dest_w` the width of the destination rectangle
219 * `dest_h` the height of the destination rectangle
220
221 ## `img:rotate(angle)`
222 Rotates the image by `angle` radians.
223
224 ## `img:flip_horizontal()`
225 Flips the image horizontally
226
227 ## `img:flip_vertical()`
228 Flips the image vertically
229
230 ## `img:flip_diagonal()`
231 Flips the image diagonally.
232
233 ## `img:orientate(n)`
234 Performs `n` 90 degree rotations on the image. `n` is the integer number of 90
235 degree rotations to perform.
236
237 ## `img:blur(radius)`
238 Blurs the image. A radious value of `0` has no effect. `1` and above determine
239 the blur matrix radius that determines how much to blur the image.
240
241 ## `img:sharpen(radius)`
242 Sharpens the image. The radius affects how much to sharpen by.
243
244 ## `img:tile_horizontal()`
245 Modifies the image so it will tile seamlessly horizontally.
246
247 ## `img:tile_vertical()`
248 Modifies the image so it will tile seamlessly vertically.
249
250 ## `img:tile()`
251 Modifies the image so it will tile seamless horizontally and vertically.
252
253 ## `img:clear()`
254 Clears the contents of the image.
255
256 ## `img:draw_pixel(x, y[, color])`
257 Draw a pixel at the specified coordinates in the given `color` (an
258 `imlib2.color` object). If no color is specified then the pixel will be drawn
259 in the most recent color.
260
261 ## `img:draw_line(x1, y1, x2, y2[, color])`
262 Draw a line from (x1, y1) to (x2, y2). If no color is specified, then it will
263 be drawn in the most recent color.
264
265 ## `img:draw_rectangle(x, y, width, height[, color])`
266 Draws the outline of a rectangle. If no color is specified, then it will be
267 drawn in the most recent color.
268
269 ## `img:fill_rectangle(x, y, width, height, color)`
270 Draws a filled rectangle. If no color is specified, then it will be drawn in
271 the most recent color.
272
273 ## `img:scroll_rectangle(x, y, width, height, delta_x, delta_y)`
274 Scrolls the specified rectangle by the given displacement.
275
276 ## `img:copy_rectangle(x, y, width, height, new_x, new_y)`
277 Copies the given rectangle to (new_x, new_y).
278
279 ## `img:fill_gradient(gradient, x, y, width, height, angle)`
280 Fills a rectangle with the given gradient.
281
282 Takes the parameters:
283
284 * `gradient` an imlib2.gradient object
285 * `x` the x coordinate of the rectangle's top left corner
286 * `y` the y coordinate of the rectangle's top left corner
287 * `width` the width of the rectangle
288 * `height` the height of the rectangle
289 * `angle` the angle at which the gradient will be drawn
290
291 ## `img:draw_ellipse(xc, yc, a, b[, color])`
292 Draws the outline of an ellipse. (xc, yc) is the centre of the ellipse, which
293 is described by the equation `(x-xc)^2/a^2 + (y-yc)^2/b^2 = 1`. If no color is
294 specified then it will be drawn in the most recent color.
295
296 Takes the parameters:
297
298 * `xc` x coordinate of the centre of the ellipse
299 * `yc` y coordinate of the centre of the ellipse
300 * `a` horizontal amplitude
301 * `b` vertical amplitude
302 * `color` (optional) an `imlib2.color` object
303
304 ## `img:fill_ellipse(xc, yc, a, b[, color])`
305 Fills an ellipse. See `img:draw_ellipse()` for the meaning of the parameters.
306
307 ## `img:draw_polygon(polygon, closed[, color])`
308 Draws the outline of a polygon. Points in the `imlib2.polygon` are drawn in
309 the order in which they were added. The final point will be connected to the
310 first point if `closed` is true. If no color is specified then it will be
311 drawn in the most recent color.
312
313 ## `img:fill_polygon(polygon[, color])`
314 Fills a `imlib2.polygon`. If no color is specified then it will be drawn in
315 the most recent color.
316
317 ## `img:draw_text(font, string, x, y[, color])`
318 Draws a string in the given font at point (x, y). If no color is specified
319 then it will be drawn in the most recent color.
320
321 Takes the parameters:
322
323 * `font` an imlib2.font object
324 * `string` the string to be drawn
325 * `x` the x coordinate of the point to start drawing
326 * `y` the y coordinate of the point to start drawing
327
328 ## `img:save(path)`
329 Saves the image to the given path. The file extension (e.g. .png or .jpg) will
330 affect the output format (but will not override any format set by a call to
331 `img:set_format()`).
332
333 Returns `true` or `nil` plus an error message if the save fails.
334
335 # `imlib2`
336 Functions to modify the operation of the imlib2 library.
337
338 ## `imlib2.set_anti_alias(bool)`
339 Enable or disable anti-aliasing for future drawing operations.
340
341 ## `imlib2.get_anti_alias()`
342 Gives a boolean indicating whether anti-aliasing is enabled or disabled.
343
344 ## `imlib2.get_cache_size()`
345 Gives the current size of the image cache in bytes
346
347 ## `imlib2.set_cache_size(size)`
348 Set the size of the image cache, where `size` is the desired cache size in
349 bytes.
350
351 ## `imlib2.flush_cache()`
352 Flushes the image cache.