Node: Images, Next: , Previous: Fonts, Up: Top


Images

The image type allows arbitrary 24-bit images to be manipulated by the window manager. Images may be both loaded from files, and rendered dynamically.

imagep arg Function
Returns t when arg is a member of the image type.

make-image file-name} &optional plist Function
Creates and returns an image object containing the image defined by the contents of the file named file-name (a string). The image-load-path directory provides the search path used while trying to find a directory containing the file named file-name.

All common image formats will likely be able to be loaded. But PNG, JPEG and XPM should always be supported.

Argument plist becomes the property list of the returned image.

Signals an error if file called file-name may be found, or if an image may not be constructed from the file.

image-directory Variable
Directory containing built-in Sawfish images. By default, this is sawfish-directory/images.

image-load-path Variable
A list of directory names. This defines the search path used when loading images. By default, this is ("." image-directory). Modifying image-directory does not modify image-load-path.

make-sized-image width height &optional color Function
Create and return a new image, of size width, height. If color is defined it specifies the color of all pixels in the image. If undefined, all pixels will be black.

make-image-from-x-drawable id &optional mask-id Function
Create and return an new image. The image is constructed by copying an X Drawable (identified by id) into a Sawfish image object. The function automatically handles depth conversion.

If mask-id is given, it identifies another X Drawable. Black pixels in this drawable indicate transparent pixels in the image object (non-black pixels have no effect on the image object).

copy-image image Function
Returns a newly allocated image object, an exact copy of the image object image.

image-dimensions image Function
Returns a cons-cell (width . height) defining the dimensions of the image represented by image.

flip-image-horizontally image Function
Flip the contents of image about the vertical axis. This is a mutating operation that returns the modified argument.

flip-image-vertically image Function
Flip the contents of image about the horizontal axis. This is a mutating operation that returns the modified argument.

flip-image-diagonally image Function
Flip the contents of image about an axis running from the top-left corner to the bottom-right corner of the image. This is a mutating operation that returns the modified argument.

As with many of the other types, arbitrary state may be associated with image objects.

image-put image property value Function
Set the property named property (a symbol) of image to value.

image-get image property Function
Return the property named property of image, or nil if no such property exists.

The only predefined property is the symbol tiled, used when an image is displayed in a window decoration. When set to a non-nil value the image is not scaled to the size of the decoration (the default), but is tiled across the decoration.

When images are scaled across border decorations the pixels that are actually scaled are defined by the border of the image. The border defines the outer rectangle of pixels that are left as-is, and the inner rectangle which is scaled.

image-border image Function
Returns a list of integers (left right top bottom), the border of the image object image.

The number associated with each edge of the image defines the number of pixels adjacent to that edge that will not be scaled.

set-image-border image left right top bottom Function
Sets the border of image.

The number associated with each edge of the image defines the number of pixels adjacent to that edge that will not be scaled.

The shape of the image may also be specified, this defines which pixels are treated as being transparent. Each image may define a single color as marking transparent pixels.

Image shapes are not supported under GDK Pixbuf. Sawfish will print a diagnostic message to STDERR if the function is called without being supported.

image-shape-color image Function
Return the color marking transparent pixels in image, or nil if no such color has been specified.

set-image-shape-color image color Function
Specify that color marks transparent pixels in image.

It's also possible to define color modifiers for each image. These define the transformation applied to the value of each pixel when it is displayed. Four different modifiers exist for each image, one for each color component, and one for the image as a whole.

image-modifier image type Function
Return the modifier defined by the symbol type of image, a list of integers (gamma brightness contrast). Each integer has a value between zero and 255 representing the weight applied to the associated attribute when rendering the image.

The four types are red, green, blue and nil (all colors). The argument must be eq to one of those symbols.

set-image-modifier image type gamma brightness contrast Function
Set the image modifier of image defined by type. Type may be one of the values of (not the symbols) red, green or blue.

There are also several other functions manipulating images:

bevel-image image border upwards &optional bevel-percent Function
Transform the edgemost pixels of image to give it a "bevelled" effect. BORDER is an integer defining the width of the bevel. If upwards is non-nil the bevel is raised, otherwise it is lowered.

If bevel-percent is defined it specifies the height or depth of the drawn bevel. When undefined, the value of the parameter is taken from the default-bevel-percent variable.

default-bevel-percent Variable
Default height of drawn bevels, as a percentage. Normally 50%.

clear-image image &optional color Function
Set all pixels in image to color (or black if color is undefined).

tile-image dest-image source-image Function
Tiles source-image into dest-image, starting from the upper-left corner, working outwards.

scale-image image width height Function
Return a copy of image, scaled to width by height pixels.

composite-images image1 image2 &optional x y Function
Copy the contents of image2 into image1. Image2 is cropped to fit. Arguments x and y indicate the position in image1 of the top-left corner of image2. If not supplied, they default to 0.

crop-image image x y width height Function
Return a new image that is a rectangular section of image. The result image starts at pixel (x, y) in image, and extends over width and height pixels in image.

When the cropped image extends beyond the boundary of image, the behavior is undefined.

The following functions allow users to manipulate images on a pixel-by-pixel level. They all use a list representation for pixels: (r, g, b, a) indicating the red, green, blue and alpha components

image-ref image x y Function
Return a list (r, g, b, a) of the red, green, blue and alpha components of the pixel (x, y) in image.

When the pixel position extends outside the bounds of the image, the behavior is undefined.

image-set image x y pixel Function
Set the pixel at (x, y) in image to pixel. Pixel is a list of four numbers (r, g, b, a), the red, green, blue and alpha components.

When the pixel position extends outside the bounds of the image, the behavior is undefined.

image-map xform image Function
Transform each pixel in image in place by calling xform on each pixel in the image.

Xform takes a single argument, a four element list (r, g, b, a) indicating the red, green, blue and alpha components of a pixel. Xform should return the new value for the pixel it was given. The return format is the same four-element list.

Xform is allowed to return nil. In this case, image-map immediately returns an invalid object.

image-fill generator image Function
Set each pixel in image based on the results of calling generator.

Generator takes two arguments: the X and Y coordinates of a pixel. It returns a four element list (r, g, b, a) indicating the red, green, blue and alpha components of a pixel. This new pixel replaces the current pixel contents at (X, Y).

Generator is allowed to return nil. In this case, image-map immediately returns an invalid object.

pixmap-cache-control max Function
Tell Sawfish to cache no more than max pixels. Returns a four-element list indicating the current cache status: (max-cached-pixels, cached-pixels, hits, misses).