ICI Modules: Imlib

Modules by name : by type

Overview

The Imlib module provides access to the Imlib image handling library. The Imlib module is intended to be used in conjunction with the X module and provides convenient functions for processing image files in various formats. The module does not attempt to provide all of Imlib's functionality but simply those functions required for getting images on screen and any others found to be needed.

Types

The Imlib module defines two new types, "data" and "image". The "data" type represents an instance of the Imlib library and is associated with a specific X11 display connection. The Imlib.init() function is used to create this object which is then used in all other Imlib module function calls.

The second type is the Imlib "image" type. This represents an image. The type supports indexing using the following keys,

rgb_width
An int.
rgb_height An int. filename A string, the name of the underlying image file, if any. width An int. height An int.

Functions

  • data = Imlib.init(display)

    The init() function is used to initialise the module and must be called prior to using any of its functions. It requires a parameter, the X11 display on which Imlib is to be run. Imlib may be operated on multiple displays concurrently, a separate call to init() for each display being all that is required (and the subsequent use of the imlib instance that corresponds to the correct display).

    The function returns a "handle" object that is used with all the other Imlib functions. Imlib calls this type "ImlibData", we refer to it simply as "data".

  • image = Imlib.load_image(data, filename)

    Loads an image from the named file and returns an Imlib image object to represent it. The image is held in memory and possibly tuned for use with the X11 display underlying the given Imlib data instance.

  • Imlib.apply_image(data, image, window)

    Takes an image and renders it to fit in the window then uses the rendered image to set both the background pixmap for the window and any image mask data to set the shape mask for the window.

  • Imlib.changed_image(data, image)

    This allows the programmer to notify imlib that the image data for the image has changed.

  • pixmap = Imlib.copy_image(data, image)

    Returns a new pixmap object that contains a copy of the image. If there is no pixmap an error is raised.

  • pixmap = Imlib.copy_mask(data, image)

    Returns a pixmap containing the mask associated with an image.

  • Imlib.destroy_image(data, image)

    Frees any resources associated with the image. The image object itself still exists but any attempt to use it will result in an "attempt to use destroyed image" error being raised.

  • Imlib.free_pixmap(data, pixmap)

    This function frees any underlying pixmap. Pixmaps created by Imlib must be freed using this function and other X11 pixmaps may be freed using it.

  • Imlib.kill_image(data, image)

    Similar to destroy_image() however this forces the image not to be cached in memory. This is useful if you know you will not be needing the image or if the image is large and you wish to conserve memory.

  • pixmap = Imlib.move_image(data, image)

    This returns the rendered pixmap underlying the given image and removes it from the image.

  • pixmap = Imlib.move_mask(data, image)

    Returns the pixmap for the image's mask and removes the pixmap from the image.

  • Imlib.paste_image(data, image, pixmap|window, x, y, w, h)

    Pastes the image at the given x,y co-ordinates in the window or pixmap. The image mask, if any, determines which pixels are drawn.

  • Imlib.render(data, image, w, h)

    Creates a pixmap representing the image at the given width and height. If the image contains transparency information a mask is rendered and associated with the image.