Extensions to gdk-pixbuf

## Extensions to gdk-pixbuf Extensions to gdk-pixbuf — Miscelleanous extensions to the gdk-pixbuf library |

## Synopsis

    #include <exo/exo.h>

    GdkPixbuf *         exo_gdk_pixbuf_colorize             (const GdkPixbuf *source,
                                                             const GdkColor *color);
    GdkPixbuf *         exo_gdk_pixbuf_frame                (const GdkPixbuf *source,
                                                             const GdkPixbuf *frame,
                                                             gint left_offset,
                                                             gint top_offset,
                                                             gint right_offset,
                                                             gint bottom_offset);
    GdkPixbuf *         exo_gdk_pixbuf_lucent               (const GdkPixbuf *source,
                                                             guint percent);
    GdkPixbuf *         exo_gdk_pixbuf_spotlight            (const GdkPixbuf *source);
    GdkPixbuf *         exo_gdk_pixbuf_scale_down           (GdkPixbuf *source,
                                                             gboolean preserve_aspect_ratio,
                                                             gint dest_width,
                                                             gint dest_height);
    GdkPixbuf *         exo_gdk_pixbuf_scale_ratio          (GdkPixbuf *source,
                                                             gint dest_size);
    GdkPixbuf *         exo_gdk_pixbuf_new_from_file_at_max_size
                                                            (const gchar *filename,
                                                             gint max_width,
                                                             gint max_height,
                                                             gboolean preserve_aspect_ratio,
                                                             GError **error);

## Description

This facility includes several functions to extend the basic functionality provided by the gdk-pixbuf library.

## Details

### exo_gdk_pixbuf_colorize ()

    GdkPixbuf *         exo_gdk_pixbuf_colorize             (const GdkPixbuf *source,
                                                             const GdkColor *color);

Creates a new GdkPixbuf based on `source`, which is colorized to `color`.

The caller is responsible to free the returned object using `g_object_unref()` when no longer needed.

`source` : | the source GdkPixbuf.
`color` : | the new color.
Returns : | the colorized GdkPixbuf.

Since 0.3.1.3

### exo_gdk_pixbuf_frame ()

    GdkPixbuf *         exo_gdk_pixbuf_frame                (const GdkPixbuf *source,
                                                             const GdkPixbuf *frame,
                                                             gint left_offset,
                                                             gint top_offset,
                                                             gint right_offset,
                                                             gint bottom_offset);

Embeds `source` in `frame` and returns the result as new GdkPixbuf.

The caller is responsible to free the returned GdkPixbuf using `g_object_unref()`.

`source` : | the source GdkPixbuf.
`frame` : | the frame GdkPixbuf.
`left_offset` : | the left frame offset.
`top_offset` : | the top frame offset.
`right_offset` : | the right frame offset.
`bottom_offset` : | the bottom frame offset.
Returns : | the framed version of `source`.

Since 0.3.1.9

### exo_gdk_pixbuf_lucent ()

    GdkPixbuf *         exo_gdk_pixbuf_lucent               (const GdkPixbuf *source,
                                                             guint percent);

Returns a version of `source`, whose pixels translucency is `percent` of the original `source` pixels.

The caller is responsible to free the returned object using `g_object_unref()` when no longer needed.

`source` : | the source GdkPixbuf.
`percent` : | the percentage of translucency.
Returns : | a translucent version of `source`.

Since 0.3.1.3

### exo_gdk_pixbuf_spotlight ()

    GdkPixbuf *         exo_gdk_pixbuf_spotlight            (const GdkPixbuf *source);

Creates a lightened version of `source`, suitable for prelit state display of icons.

The caller is responsible to free the returned pixbuf using #`g_object_unref()`.

`source` : | the source GdkPixbuf.
Returns : | the lightened version of `source`.

Since 0.3.1.3

### exo_gdk_pixbuf_scale_down ()

    GdkPixbuf *         exo_gdk_pixbuf_scale_down           (GdkPixbuf *source,
                                                             gboolean preserve_aspect_ratio,
                                                             gint dest_width,
                                                             gint dest_height);

Scales down the `source` to fit into the given `width` and `height`. If `aspect_ratio` is `TRUE` then the aspect ratio of `source` will be preserved.

If `width` is larger than the width of `source` and `height` is larger than the height of `source`, a reference to `source` will be returned, as it's unneccesary then to scale down.

The caller is responsible to free the returned GdkPixbuf using `g_object_unref()` when no longer needed.

`source` : | the source GdkPixbuf.
`preserve_aspect_ratio` : | `TRUE` to preserve aspect ratio.
`dest_width` : | the max width for the result.
`dest_height` : | the max height for the result.
Returns : | the resulting GdkPixbuf.

Since 0.3.1.1

### exo_gdk_pixbuf_scale_ratio ()

    GdkPixbuf *         exo_gdk_pixbuf_scale_ratio          (GdkPixbuf *source,
                                                             gint dest_size);

Scales `source` to `dest_size` while preserving the aspect ratio of `source`.

`source` : | The source GdkPixbuf.
`dest_size` : | The target size in pixel.
Returns : | A newly created GdkPixbuf.

### exo_gdk_pixbuf_new_from_file_at_max_size ()

    GdkPixbuf *         exo_gdk_pixbuf_new_from_file_at_max_size
                                                            (const gchar *filename,
                                                             gint max_width,
                                                             gint max_height,
                                                             gboolean preserve_aspect_ratio,
                                                             GError **error);

Creates a new GdkPixbuf by loading an image from the file at `filename`. The file format is detected automatically. If `NULL` is returned, then `error` will be set. Possible errors are in the GDK_PIXBUF_ERROR and G_FILE_ERROR domains. If the image dimensions exceed `max_width` or `max_height`, the image will be scaled down to fit into the dimensions, optionally preservingthe image's aspect ratio. The image may still be larger, depending on the loader.

The advantage of using this function over `gdk_pixbuf_new_from_file_at_scale()` is that images will never be scaled up, whichwould otherwise result in ugly images.

`filename` : | name of the file to load, in the GLib file name encoding.
`max_width` : | the maximum width of the loaded image.
`max_height` : | the maximum height of the loaded image.
`preserve_aspect_ratio` : | `TRUE` to preserve the image's aspect ratio while scaling to fit into `max_width` and `max_height`.
`error` : | return location for errors or `NULL`.
Returns : | a newly created GdkPixbuf with a reference count or 1, or `NULL` if any of several error conditions occurred: the file could not be opened, there was no loader for the file's format, there was not enough memory to allocate the buffer for the image, or the image file contained invalid data.

Since 0.3.1.9