functions

Below is a list of All Imlib functions - the Xlib version first, then the GDK version listed second. GDK Imlib functions do not use the ImlibData pointer at the start, and so this parameter, being common to ALL Xlib Imlib functions will not be mentioned, but it will be assumed you realise that it is required.

  ImlibData *Imlib_init(Display *disp);
  void gdk_imlib_init();


This function inititalised Imlib. It must be called early in the program BEFORE any other Imlib functions are called. You must call it AFTER you call XOpenDisplay or gdk_init. The Xlib version needs to have the display variable passed to it. The Xlib version is capable of running on multiple displays - you just init Imlib per display variable.This function causes Imlib to investigate properties of your XServer - ie, is the shared memory extension available? - if so, use it. The depth(s) of the visual(s) and choosing the best visual, initializing the caches to be empty, load a default palette (if in 8bpp) and set up a dither matrix etc. the default palette file is defined in the system or users imrc file as PaletteFile which is simply a flat file of line delimited colors, each color being space separated hexadecimal values for red, green and blue. See the sample palette file provided with Imlib. You can also force Imlib's shared memory use off in the system or user's imrc files with the Mit-Shm option - shared pixmaps are available if this is turned on, but it is currently advised to turn shared pixmaps off due to Xserver design flaws. Some operating systems define maximum chunk sizes for shared memory blocks, and so Imlib can be told not to create images of greater than a certain size in bytes with the Shm_Max_Size option in the imrc file. Image and pixmap caches can be turned on or off and set to their sizes here as well.

  ImlibData *Imlib_init_with_params(Display *disp,
  ImlibInitParams *p);
  void gdk_imlib_init_params(GdkImlibInitParams *p);


This function inititalised Imlib, BUT allows the programmer to specify startup parameters that override the users or system imrc file. Use these options with cauthion, as it is assumed you know what you are doing.

The structure containing the parameters to giv Imlib is:

  typedef struct _ImlibInitParams
  {
     int flags;
     int visualid;
     char *palettefile;
     char sharedmem;
     char sharedpixmaps;
     char paletteoverride;
     char remap;
     char fastrender;
     char hiquality;
     char dither;
     int imagecachesize;
     int pixmapcachesize;
  } ImlibInitParams;
  #define PARAMS_VISUALID 1


with a simliar one for gdk (same members), and same defines for the flags.You set the bits in the flags member with the appropriate defines (PARAMS_VISUALID | PARAMS_PALETTEFILE | PARAMS_SHAREDMEM etc.) which flag whihc members of the structure are actually relevant and should be used by Imlib in overriding the user/system defaults. If the flag bit is set, then that structure member is used. the members are as follows:

visualid
contains an int with the visualid to be used by Imlib.
palettefile
string containing the file for the palette file.
sharedmem
is 1 if you want shared memory used, otherwise 0.
sharedpixmaps
is 1 if you want shared pixmaps, otherwise 0.
paletteoverride
1 if palette remapping is to be forced on, otherwise 0.
remap
1 for fast remapping 0 for slower more accurate remapping.
fastrender
1 for fast rendering, 0 for slightly slower rendering.
hiquality
1 to turn dithering on in 15/16bpp, 0 otherwise.
dither
1 to turn dithering on in 8bpp or less, otherwise 0.
imagecachesize
the size of the image cache to be used in bytes.
pixmapcachesize
the size of the pixmap cache to be used in bits.

Remember the member is ignored if the flags does not contain the bit set for that member - if the bit is set, then that member is used.

  int Imlib_get_render_type(ImlibData *id);
  gint gdk_imlib_get_render_type();


This function returns Imlib's current rendering mode. It will return one of:



These modes determine how images will appear when rendered as pixmaps. The first 4 modes are for 8-bit displays only (though they can be used for higher bit displays after the loading of a palette - Imlib won't load a palette in higher display depths to save time). If you wish to use these lower modes in higher bit depths, you will need to call Imlib_load_colors or gdk_imlib_load_colors on a palette file. You can replace the default palette any time by first calling Imlib_free_colors or gdk_imlib_free_colors. The first 2 modes do not dither the images, and thus are faster. The fast versions used a quick 32x32x32 colorcube lookup to obtain a best color match the other versions use a slightly more accurate color matching function, but are slower. Dithering gives much better results, but is slower. Dithering and Fast remapping are turned on or of in the users or system imrc file. See this file and its comments for details. You can ALSO override Imlib using truecolor renderers, and force it to use paletted dithered images in higher bit depths by turning these render types on, or turning PaletteOverride on in the system or user's imrc file.RT_PLAIN_TRUECOL is used for all higher bit depths (Imlib won't allow this mode to be set if the depth is less than or equal to 8 bit). This s a fast renderer that provides high quality. RT_DITHER_TRUECOL is an even higher quality renderer that only has effect in 15 and 16 bit depths. It dithers in these modes to provide the highest quality images. This option is turned on by the HighQuality option in the user's or system imrc file.

  void Imlib_set_render_type(ImlibData *id, int rend_type);
  void gdk_imlib_set_render_type(gint rend_type);


This function sets the render type to rend_type which should be one of the above listed render types. This is optional and Imlib will default to settings provided by the user, system and Xserver. This is primarily here, in conjunction with Imlib_get_render_type or gdk_imlib_get_render_type to allow fine tweaking by applications of Imlib's rendering performance.

  int Imlib_load_colors(ImlibData *id, char *file);
  gint gdk_imlib_load_colors(char *file);


This function loads the named palette file (described in Imlib_init). It is advised to call Imlib_free_colors or gdk_imlib_free_colors first before calling this. There may be strange effects when changing palettes "on the fly" in 8-bit color. All pixmaps should be re-rendered to inherit this new palette.

  ImlibImage *Imlib_load_image(ImlibData *id, char *file);
  GdkImlibImage *gdk_imlib_load_image(char *file);


This function loads the named file and returns a pointer to an image structure. Imlib will first check to see if the file has magic numbers defining it as a file Imlib can natively read and then attempt to read it. If Imlib doesn't recognise the magic numbers, or certain native loaders have not been compiled in, it will fall back to asking Imagemagick's convert utility to convert the image into a PPM format image for Imlib to read in. If this doesn't work, Imlib will call on the NETPBM utilities to convert the image to a PPM for Imlib to read. If this fails, Imlib gives up and returns NULL. Imlib does not create any temporary files in this process.

Imlib can, if all native loaders are compiled in, read JPEG, GIF, PPM, PGM, XPM, PNG, TIFF and EIM image formats. GIF, PNG, XPM, TIFF and EIM images all retain their transparency information when being loaded.

  int Imlib_best_color_match(ImlibData *id, int *r, int *g, int
  *b);
  gint gdk_imlib_best_color_match(gint *r, gint *g, gint *b);


If the render type is a truecolor one, Imlib returns a pixel value that is the closest match to the requested RGB value (RGB each being in the range of 0-255). This will normally be very close. If using a palette render type, Imlib returns the closest match to the allocated palette and the rgb members are set to the actual RGB value of the color returned, The function always returns the pixel value of this color.

  int Imlib_render(ImlibData *id, ImlibImage *image, int width,
  int height);
  gint gdk_imlib_render(GdkImlibImage *image, gint width, gint
  height);


This will render the image pointed to by image into a pixmap of the defined width and height. If the image contains transparency, a mask will also be rendered. These can be extracted form the image using the functions below. If any pixmaps were already existant in the image, these are destroyed upon re-rendering the image. If Imlib was unable for some reason to render the Image to that pixmap, it will return 0, otherwise it will return 1.

  Pixmap Imlib_copy_image(ImlibData *id, ImlibImage *image);
  GdkPixmap *gdk_imlib_copy_image(GdkImlibImage *image);


This routine returns a copy of the image pixmap. You should use this routine if you wish to modify the pixmap itself afterwards by doing any drawing on it. Do NOT use the move functions for pixmap that will be modified later. You can make multiple copies of the pixmap by calling this function repeatedly. If no pixmap was rendered it will return 0 or NULL.

  Pixmap Imlib_copy_mask(ImlibData *id, ImlibImage *image);
  GdkBitmap *gdk_imlib_copy_mask(GdkImlibImage *image);


This is the Imlib_copy_image or gdk_imlib_copy_image functions, but it returns the mask for the image. If there is no transparency, or no mask was rendered, it returns 0, or NULL.

  Pixmap Imlib_move_image(ImlibData *id, ImlibImage *image);
  GdkPixmap *gdk_imlib_move_image(GdkImlibImage *image);


This returns the rendered pixmap from the image structure, and removes the image pixmap (setting it to 0 or NULL) inside the image structure. If you do not need to modify the pixmap - ie just use it, this is the function you should call. It is faster than Imlib_copy_image or gdk_imlib_copy_image.

  Pixmap Imlib_move_mask(ImlibData *id, ImlibImage *image);
  GdkBitmap *gdk_imlib_move_mask(GdkImlibImage *image);


This is the same as Imlib_move_image or gdk_imlib_move_image but returns the mask for the rendered Image.

  void Imlib_destroy_image(ImlibData *id, ImlibImage *image);
  void gdk_imlib_destroy_image(GdkImlibImage *image);


This destroys the Image structure, making it invalid. It reduces the reference count on that image and if at zero, it enters the cache. Once the cache fills and this image gets to the oldest part of the cache, it will be freed when the cache exceeds its boundaries.

  void Imlib_kill_image(ImlibData *id, ImlibImage *image);
  void gdk_imlib_kill_image(GdkImlibImage *image);


This does the same as Imlib_destroy_image or gdk_imlib_destroy_image but forces it to be freed immediately once its reference count hits zero - ie it does not hang around in the cache.

  void Imlib_free_colors(ImlibData *id);
  void gdk_imlib_free_colors();


This frees the current colormap used by Imlib and all the colors in it, setting the color count to zero. It is not a good idea to go rendering anything in an 8-bit display if the colors are freed.

  void Imlib_free_pixmap(ImlibData *id, Pixmap pixmap);
  void gdk_imlib_free_pixmap(GdkPixmap *pixmap);


This frees the pixmap pointed to - reducing its reference count by 1. If the count is zero it enters the cache and once the cache is filled and the pixmap is too old, it is freed. You must use this function for ALL pixmaps generated by Imlib. You may use it on Pixmaps not generated by Imlib and it will free them as normal. This function ALSO frees (or reduces the reference count) on the associated mask pixmap for that image pixmap, if there is a mask, so you do not need to free the mask separately.

  void Imlib_get_image_border(ImlibData *id, ImlibImage *image,
  ImlibBorder *border);
  void gdk_imlib_get_image_border(GdkImlibImage *image,
  GdkImlibBorder *border);


This function returns the image's border attributes in the border structure.

  void Imlib_set_image_border(ImlibData *id, ImlibImage *image,
  ImlibBorder *border);
  void gdk_imlib_set_image_border(GdkImlibImage *image,
  GdkImlibBorder *border);


This function sets the image's border attributes to those in the border structure.

  void Imlib_get_image_shape(ImlibData *id, ImlibImage *image,
  ImlibColor *color);
  void gdk_imlib_get_image_shape(GdkImlibImage *image,
  GdkImlibColor *color);


This function returns the color of the transparent color in an image - if there is no transparent color the RGB members are all set to -1, otherwise they are set to the RGB value of this color.

  void Imlib_set_image_shape(ImlibData *id, ImlibImage *image,
  ImlibColor *color);
  void gdk_imlib_set_image_shape(GdkImlibImage *image,
  GdkImlibColor *color);


This function sets the transparent color to the RGB values in the color structure. If any of these are -1, transparency for that image is turned off.

  int Imlib_save_image_to_eim(ImlibData *id, ImlibImage *image,
  char *file);
  gint gdk_imlib_save_image_to_eim(GdkImlibImage *image, char
  *file);


This Function saves the image into an EIM format image. EIM image format is currently under construction. Please come back later.

  int Imlib_add_image_to_eim(ImlibData *id, ImlibImage *image,
  char *file);
  gint gdk_imlib_add_image_to_eim(GdkImlibImage *image, char
  *file);


This Function adds the image into an EIM file that currently exists. EIM image format is currently under construction. Please come back later.

  int Imlib_save_image_to_ppm(ImlibData *id, ImlibImage *image,
  char *file);
  gint gdk_imlib_save_image_to_ppm(GdkImlibImage *image, char
  *file);


This function saves the current image as a binary format PPM file. If it is successful, it returns 1, otherwise it returns

  int Imlib_load_file_to_pixmap(ImlibData *id, char *filename,
  Pixmap *pmap, Pixmap *mask);
  gint gdk_imlib_load_file_to_pixmap(char *filename, GdkPixmap
  **pmap, GdkBitmap **mask);


This is a macro function that does the following. It loads the named image file, and sets the pmap and mask variables to the image pixmap and mask pixmaps that are rendered at the image's original size. It returns 1 if successful and 0 if the load and render do not succeed. It frees the image after loading. The pixmaps should be freed by Imlib_free_pixmap or gdk_imlib_free_pixmap. This is a nigh identical replacement for XpmReadFileToPixmap or gdk_pixmap_create_from_xpm.

  void Imlib_set_image_modifier(ImlibData *id, ImlibImage *im,
  ImlibColorModifier *mod);
  void gdk_imlib_set_image_modifier(GdkImlibImage *im,
  GdkImlibColorModifier *mod);


This function sets the image's brightness, contrast and gamma settings to those defined in the mod structure. You need to re-render the image to make this have any effect.

  void Imlib_set_image_red_modifier(ImlibData *id, ImlibImage
  *im, ImlibColorModifier *mod);
  void gdk_imlib_set_image_red_modifier(GdkImlibImage *im,
  GdkImlibColorModifier *mod);


This function sets the image's red channel brightness, contrast and gamma settings to those defined in the mod structure. You need to re-render the image to make this have any effect.

  void Imlib_set_image_green_modifier(ImlibData *id, ImlibImage
  *im, ImlibColorModifier *mod);
  void gdk_imlib_set_image_green_modifier(GdkImlibImage *im,
  GdkImlibColorModifier *mod);


This function sets the image's green channel brightness, contrast and gamma settings to those defined in the mod structure. You need to re-render the image to make this have any effect.

  void Imlib_set_image_blue_modifier(ImlibData *id, ImlibImage
  *im, ImlibColorModifier *mod);
  void gdk_imlib_set_image_blue_modifier(GdkImlibImage *im,
  GdkImlibColorModifier *mod);


This function sets the image's blue channel brightness, contrast and gamma settings to those defined in the mod structure. You need to re-render the image to make this have any effect.

  void Imlib_get_image_modifier(ImlibData *id, ImlibImage *im,
  ImlibColorModifier *mod);
  void gdk_imlib_get_image_modifier(GdkImlibImage *im,
  GdkImlibColorModifier *mod);


This function returns the image's current modifier settings in the mod structure.

  void Imlib_get_image_red_modifier(ImlibData *id, ImlibImage
  *im, ImlibColorModifier *mod);
  void gdk_imlib_get_image_red_modifier(GdkImlibImage *im,
  GdkImlibColorModifier *mod);


This function returns the image's red channel modifier settings in the mod structure.

  void Imlib_get_image_green_modifier(ImlibData *id, ImlibImage
  *im, ImlibColorModifier *mod);
  void gdk_imlib_get_image_green_modifier(GdkImlibImage *im,
  GdkImlibColorModifier *mod);


This function returns the image's green channel modifier settings in the mod structure.

  void Imlib_get_image_blue_modifier(ImlibData *id, ImlibImage
  *im, ImlibColorModifier *mod);
  void gdk_imlib_get_image_blue_modifier(GdkImlibImage *im,
  GdkImlibColorModifier *mod);


This function returns the image's blue channel modifier settings in the mod structure.

  void Imlib_set_image_red_curve(ImlibData *id, ImlibImage *im,
  unsigned char *mod);
  void gdk_imlib_set_image_red_curve(GdkImlibImage *im, unsigned
  char *mod);


This function sets the mapping table curve for the red channel to the contents of the array pointer to by mod, which is a 256 element array of unsigned char values that map newvalue=mod[value]. This overrides the current modifier table generated by any gamma, brightness or contrast settings.

  void Imlib_set_image_green_curve(ImlibData *id, ImlibImage *im,
  unsigned char *mod);
  void gdk_imlib_set_image_green_curve(GdkImlibImage *im,
  unsigned char *mod);


This function sets the mapping table curve for the green channel to the contents of the array pointer to by mod, which is a 256 element array of unsigned char values that map newvalue=mod[value]. This overrides the current modifier table generated by any gamma, brightness or contrast settings.

  void Imlib_set_image_blue_curve(ImlibData *id, ImlibImage *im,
  unsigned char *mod);
  void gdk_imlib_set_image_blue_curve(GdkImlibImage *im, unsigned
  char *mod);


This function sets the mapping table curve for the blue channel to the contents of the array pointer to by mod, which is a 256 element array of unsigned char values that map newvalue=mod[value]. This overrides the current modifier table generated by any gamma, brightness or contrast settings.

  void Imlib_get_image_red_curve(ImlibData *id, ImlibImage *im,
  unsigned char *mod);
  void gdk_imlib_set_image_red_curve(GdkImlibImage *im, unsigned
  char *mod);


This function returns the current red channel mapping table curve by copying its contents into the 256 element array of unsigned char's pointed to by mod.

  void Imlib_get_image_green_curve(ImlibData *id, ImlibImage *im,
  unsigned char *mod);
  void gdk_imlib_get_image_green_curve(GdkImlibImage *im,
  unsigned char *mod);


This function returns the current green channel mapping table curve by copying its contents into the 256 element array of unsigned char's pointed to by mod.

  void Imlib_get_image_blue_curve(ImlibData *id, ImlibImage *im,
  unsigned char *mod);
  void gdk_imlib_get_image_blue_curve(GdkImlibImage *im, unsigned
  char *mod);


This function returns the current blue channel mapping table curve by copying its contents into the 256 element array of unsigned char's pointed to by mod.

  void Imlib_apply_modifiers_to_rgb(ImlibData *id, ImlibImage
  *im);
  void gdk_imlib_apply_modifiers_to_rgb(GdkImlibImage *im);


This function takes all the current RGB mapping tables and modifies the original 24-bit RGB data to match. This dirties all cached pixmaps of that image, and you will need to re-render the image for it to take any effect.

  void Imlib_changed_image(ImlibData *id, ImlibImage *im);
  void gdk_imlib_changed_image(GdkImlibImage *im);


If you go and modify the image's RGB data yourself via your own routines, once finished and before rendering any more pixmaps, you should call this function to inform Imlib that the contents of the image have changed.

  void Imlib_apply_image(ImlibData *id, ImlibImage *im, Window
  p);
  void gdk_imlib_apply_image(GdkImlibImage *im, GdkWindow *p);


This function takes an image, renders it at the size of the window specified as p, sets the window's background pixmap to be this rendered pixmap, and sets the window's shape mask to the the mask for the image if it has any transparency. It frees both pixmaps after use.

  void Imlib_paste_image(ImlibData *id, ImlibImage *im, Window p,
  int x, int y, int w, int h);
  void gdk_imlib_paste_image(GdkImlibImage *im, GdkWindow *p,
  gint x, gint y, gint w, gint h);


This pastes a pixmap of the image at the x,y co-ordinates in the drawable p (which can be either a window or a pixmap), and uses the shape mask to determine which pixels are actually drawn. It is effectively like pasting the image at that size at that location. Both the pixmap and the mask are freed afterwards.

  void Imlib_paste_image_border(ImlibData *id, ImlibImage *im,
  Window p, int x, int y, int w, int h);
  void gdk_imlib_paste_image_border(GdkImlibImage *im, GdkWindow
  *p, gint x, gint y, gint w, gint h);


This function works just like Imlib_paste_image or gdk_imlib_paste_image, but only pastes the borders of the image. This is handy if the image is being used to define bevel borders on a button for maximum efficiency.

  void Imlib_flip_image_horizontal(ImlibData *id, ImlibImage
  *im);
  void gdk_imlib_flip_image_horizontal(GdkImlibImage *im);


This flips the RGB data in an image horizontally. You need to re-render the image for it to take effect.

  void Imlib_flip_image_vertical(ImlibData *id, ImlibImage *im);
  void gdk_imlib_flip_image_vertical(GdkImlibImage *im);


This flips the RGB data in an image vertically. You need to re-render the image for it to take effect.

  void Imlib_rotate_image(ImlibData *id, ImlibImage *im, int d);
  void gdk_imlib_rotate_image(GdkImlibImage *im, gint d);


This function currently is a bit of a misnomer. It does not use the d parameter - it merely mirrors the image about a diagonal line going from the top-left to the bottom right at 45 degrees. It effectively rotates the image, combined with flips horizontally and vertically this can be used to give the image any orientation in steps of 90 degrees. This function needs some work (it must use the d parameter to work out which way to rotate and how much - 1 rotates clockwise, -1 counter-clockwise by 90 degrees, 2 or -2 180 degrees etc.)

  ImlibImage *Imlib_create_image_from_data(ImlibData *id,
  unsigned char *data, unsigned char *alpha, int w, int h);
  GdkImlibImage *gdk_imlib_create_image_from_data(unsigned char
  *data, unsigned char *alpha, gint w, gint h);


This function take a pointer to 24-bit RGB data (in the format RGBRGBRGB) and creates an image of size w x h out of it that can then be used by Imlib's routines for rendering. The pointer to the alpha data is currently unused and is there for future use. If successful it returns a pointer to the image, or NULL of unsuccessful. The data pointed to is copied into the image. This means you may free or destroy this original data or do with it as you see fit without affecting Imlib's image.

  ImlibImage *Imlib_clone_image(ImlibData *id, ImlibImage *im);
  GdkImlibImage *gdk_imlib_clone_image(GdkImlibImage *im);


This function makes a duplicate copy of the image pointed to. If unsuccessful it returns NULL, otherwise it returns a pointer to the new image.

  ImlibImage *Imlib_clone_scaled_image(ImlibData *id, ImlibImage
  *im, int w, int h);
  GdkImlibImage *gdk_imlib_clone_scaled_image(GdkImlibImage *im,
  int w, int h);


This Function creates a duplicate image scaled to the size w x h of the image pointed to - the 24-bit data is what is scaled. If successful it returns a pointer to the new image or NULL if not.

  int Imlib_get_fallback(ImlibData *id);
  gint gdk_imlib_get_fallback();


This function gets the status of ImageMagick and NETPBM fallback mechanisms. 1 means they are active, 0 means they are not.

  void Imlib_set_fallback(ImlibData *id, int fallback);
  void gdk_imlib_set_fallback(gint fallback);


This function sets the state of the ImageMagick and NETPBM fallback mechanisms. 1 makes them active, 0 deactivates them.

  Visual *Imlib_get_visual(ImlibData *id);
  GdkVisual *gdk_imlib_get_visual();


This function returns the Visual that Imlib has decided to use (accoridng to imrc and XServer capabilities).

  Colormap Imlib_get_colormap(ImlibData *id);
  GdkColormap *gdk_imlib_get_colormap();


This function returns the Colormap that Imlib has chosen to use for its visual.

  char *Imlib_get_sysconfig(ImlibData *id);
  gchar *gdk_imlib_get_sysconfig();


This function returns a pointer to a copy of the path to the system imrc file. When finished you should free this string.

  ImlibImage *Imlib_create_image_from_xpm_data(ImlibData *id,
  char **data);
  GdkImlibImage *gdk_imlib_create_image_from_xpm_data(char
  **data);


This function creates an Imlib image out of an inlined XPM image (ie. #include "file.xpm"). data is the pointer to the XPM data.

  gint gdk_imlib_data_to_pixmap(char **data, GdkPixmap **pmap,
  GdkBitmap **mask);
  int Imlib_data_to_pixmap(ImlibData *id, char **data, Pixmap
  *pmap, Pixmap *mask);


This function creates a pixmap (and optionally a mask) out of the data pointed to by data. This data is in the form of an XPM file that has been included into the source (eg #include "file.xpm"). If the XPM data has no transparency the mask is set to 0 or NULL. The pmap is set to the pixmap created. If the operation fails 0 is returned, otherwise 1 is returned.

  void gdk_imlib_crop_image(GdkImlibImage *im, gint x, gint y,
  gint w, gint h);
  void Imlib_crop_image(ImlibData *id, ImlibImage *im, int x, int
  y, int w, int h);


When called, this function will crop out the section of the 24-bit original image specified by the rectangle with its top-left corner at (x,y) and with width w and height h in pixels. These pixels are pixels in the original 24-bit data held in the image structure, not a scaled down or up rendered version.

  GdkImlibImage *gdk_imlib_crop_and_clone_image(GdkImlibImage
  *im, gint x, gint y, gint w, gint h);
  ImlibImage *Imlib_crop_and_clone_image(ImlibData *id,
  ImlibImage *im, int x, int y, int w, int h);


When called, this function will crop out the section of the 24-bit original image specified by the rectangle with its top-left corner at (x,y) and with width w and height h in pixels. These pixels are pixels in the original 24-bit data held in the image structure, not a scaled down or up rendered version. Instead of modifying the original, it makes a copy of the Image and returns that. NULL is returned if the crop fails.

  void gdk_imlib_best_color_get(GdkColor *c);


This is a gdk_imlib only API call, as much of GTK and GDK pass GdkColor structs around, and so Imlbi will fill the pixel value of the GdkColro and set the red, green and blue members to a member form Imlib's palette (unless it is in 15bpp or higher and palette remapping sin't forced), thus conserving colors wherever possible. In truecolor and higher it will give exact matches.

  gint gdk_imlib_save_image(GdkImlibImage *im, char *file,
  GdkImlibSaveInfo *info);
  int Imlib_save_image(ImlibData *id, ImlibImage *im, char *file,
  ImlibSaveInfo *info);


This function is for those who want brain-dead saving in a single function. It will save the image pointed to as the file passed. The extension is used to determine filetype to save as, so saving as image.jpg will save as a jpeg, or saving as file.png will save as a png file etc. The info pointer can be NULL, in which case the image will be saved with certain settings if the format supports it. for example a jpeg image will always be saved at 80% quality unless you provide a pointer to this structre and set the quality member to a value from 0 to 256, 256 being 100% quality, 0 being 0% quality. Only jpeg images use this member. The other members of the info structure are used for postscript saving, so if you plan to output as a postscript, file set the members in the structure. The scaling member is a value, with 1024 meaning "scale the image to maximum size on paper", 512 meaning "half the paper size" and 0 meaning zero size. you can use larger values, but the image will be clipped to the border of your paper. The color member is either 0 or 1 1 meaning save as color, 0 meaning save as grayscale. the x and yjustification members specify a justification in the x and y directions (on paper relative to the bottom-left of the page) - 1024 meaning right or top justify, 0 meaning left or bottom justify. Using values inbetween (like 512,512) will give center justification or many variations inbetween.

The page_size member can be one of PAGE_SIZE_EXECUTIVE, PAGE_SIZE_LETTER, PAGE_SIZE_LEGAL, PAGE_SIZE_A4, PAGE_SIZE_A3, PAGE_SIZE_A5, or PAGE_SIZE_FOLIO. This specifies the page size for the postscript output.

  GdkImlibImage *gdk_imlib_create_image_from_drawable(GdkWindow
  *gwin, GdkBitmap *gmask, int x, int y, int width, int height);
  ImlibImage *Imlib_create_image_from_drawable(ImlibData *id,
  Drawable win, Pixmap mask, int x, int y, int width, int
  height);


These functions create an Imlib Image out of an X drawable. The Drawable (win or gwin) is either a pixmap or a window. The mask is a mask pixmap (optional for creating the mask for the image - currently unused - reserved for future use). X, y, width and height describe a rectangle inside the drawable (x, and y being relative to the drawable's top-left corner). This function, if successful will return a pointer to an image (NOTE to advanced programmers - this function internally performs server grabs it means if you had a grab before this function you will no longer have it afterwards. This is necessary to avoid race conditions that could kill your client).
author: The Rasterman