chickadee » imlib2

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

imlib2

Description

Chicken bindings for the imlib2 image library.

Author

Peter Bex

Maintainer

Moritz Heidkamp

Requirements

None

Documentation

Note that currently not all imlib2 functionality has been added to this egg.

Font loading

font-load filename sizeprocedure

Load and return a true type font from file filename sized size pixels. This respects the system's font path.

Image creation, destruction and friends

image-create width heightprocedure

Returns a new imlib2 image object which represents a transparent image of the given size.

image? imgprocedure

Determine if img is an imlib image.

image-destroy imgprocedure

Destroy the given image object.

image-clone imgprocedure

Create a fresh copy of the image object img.

image-load filenameprocedure

Returns a new imlib image object which represents the image stored in the file filename. This automatically uses the correct loader, as determined by Imlib2 on the basis of the file's extension.

image-save img filenameprocedure

Store the imlib image object represented by img in the file filename. The right loader is automatically selected by Imlib2 if you haven't set it explicitly with image-format-set!.

make-image pointerprocedure

Construct an imlib image object for pointer.

Image properties

image-format imgprocedure

Request the currently set format for the image, or #f if no format has been associated with it yet.

image-format-set! img formatprocedure

Explicitly set the file format on the image for subsequent calls to image-save. The format argument is passed to the loaders in the same way a file extension would be.

image-width imgprocedure

Returns the width of the supplied image, in pixels.

image-height imgprocedure

Returns the height of the supplied image, in pixels.

image-filename imgprocedure

Returns the original filename for the image, if it was loaded from a file. Otherwise it returns #f.

image-alpha? imgprocedure

Does the image have an alpha layer?

image-alpha-set! img valueprocedure

Enable or disable alpha layer support for the image.

image-track-changes-on-disk imgprocedure

From now on, track changes on disk to the file that is associated with img. 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.

image-get-data-for-reading-only imgprocedure

Get a read-only pointer on img's content data.

Image manipulation operations

All these operations create a copy of the image. This can eat a lot of memory if you're not careful. Use the methods ending with a bang if you just want to destructively update an existing image.

Blending
(image-blend img src-img #!key (merge-alpha #t) (src-x 0) (src-y 0) (src-width (image-width src-img)) (src-height (image-height src-img)) (dest-x 0) (dest-y 0) (dest-width (image-width src-img)) (dest-height (image-height src-img)))procedure
(image-blend! img src-img #!key (merge-alpha #t) (src-x 0) (src-y 0) (src-width (image-width src-img)) (src-height (image-height src-img)) (dest-x 0) (dest-y 0) (dest-width (image-width src-img)) (dest-height (image-height src-img)))procedure

Blend src-img onto img, possibly cropping and scaling it. The default behavior is to blend src-img in total and in its original size onto the top left corner of img.

Orientation
image-flip-horizontal imgprocedure
image-flip-horizontal! imgprocedure

Horizontally flip img.

image-flip-vertical imgprocedure
image-flip-vertical! imgprocedure

Vertically flip img.

image-flip-diagonal imgprocedure
image-flip-diagonal! imgprocedure

Diagonally flip img. This works like transposing a matrix.

image-orientate img orientationprocedure
image-orientate! img orientationprocedure

Orientate img. According to imlib2 documentation, this procedure rotates the image by 90 degrees orientation times. However, the procedure accepts values between 0 and 7, inclusive. What values 4-7 do, I'm not really sure of. They appear to rotate the image (mod orientation 3) times 90 degrees, but flip it as well.

Texture/retouching procedures
image-sharpen img radiusprocedure
image-sharpen! img radiusprocedure

Sharpen img. The radius 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.

image-blur img radiusprocedure
image-blur! img radiusprocedure

Blur img. The radius argument is a positive integer indicating the blur matrix radius, so 0 has no effect.

image-tile imgprocedure
image-tile! imgprocedure
image-tile-horizontal imgprocedure
image-tile-horizontal! imgprocedure
image-tile-vertical imgprocedure
image-tile-vertical! imgprocedure

Adjust img in such a way around the edges, such that it is suitable for use in repeating ("tiled") patterns on all sides, only horizontally or only vertically.

image-crop img x y width heightprocedure
image-crop! img x y width heightprocedure

Crop img. The x and y parameters indicate the upper left pixel of the new image. The width and height parameters indicate the size of the new image. Returns #f on failure.

Note: This procedure 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.

image-scale img width heightprocedure

Create a new, scaled copy of the image.

image-crop&scale img src-x src-y src-width src-height dest-width dest-heightprocedure

Create a new, cropped and scaled copy of img. The arguments src-x, src-y, src-width and src-height indicate cropping dimensions as per image-crop, in the original image. The dest-width and dest-height arguments indicate the new image's width and height.

Pixel query procedures

image-pixel/rgba img x yprocedure

Returns the RGBA (red, green, blue, alpha) color values for the image at the specified pixel coordinate as 4 values.

image-pixel/hsva img x yprocedure

Returns the HSVA (hue, saturation, value, alpha) color values for the image at the specified pixel coordinate as 4 values.

image-pixel/hlsa img x yprocedure

Returns the HLSA (hue, lightness, saturation, alpha) color values for the image at the specified pixel coordinate as 4 values.

image-pixel/cmya img x yprocedure

Returns the CMYA (cyan, magenta, yellow, alpha) color values for the image at the specified pixel coordinate as 4 values.

Color specifiers

Note: This could use some more work. Perhaps the procedures from the previous section should return values of these types instead.

color? colorprocedure

Is the specified object an imlib color specifier?

color/rgba r g b aprocedure

Create a color specifier for the given RGBA values.

color/hsva h s v aprocedure

Create a color specifier for the given HSVA values.

color/hlsa h l s aprocedure

Create a color specifier for the given HLSA values.

color/cmya c m y aprocedure

Create a color specifier for the given CMYA values.

Drawing procedures

The following procedures all destructively update the image object.

Shapes and Pixels
image-draw-pixel img color x yprocedure

Draw a pixel in the given image on the given coordinates with the given color specifier.

image-draw-line img color x1 y1 x2 y2procedure

Draw a line in the image from the coordinates (x1,y1) to (x2,y2).

image-draw-rectangle img color x y width heightprocedure

Draw a one-pixel wide outline of a rectangle with the given color. The x and y coordinates are of the upper left corner of the rectangle.

image-fill-rectangle img color x y width heightprocedure

Same as image-draw-rectangle, but filled in.

Text
image-draw-text img font color x y text #!optional (direction 'to-right) (angle #f)procedure

Draw the string text on img at coordinates x / y with color and font. Possible direction symbols are to-right, to-left, to-down, to-up and to-angle. The optional angle argument must be supplied when direction is to-angle.

Changelog

License

 Copyright (c) 2005-2011, Peter Bex
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 Neither the name of the author nor the names of its contributors may
 be used to endorse or promote products derived from this software
 without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.

Contents »