The gdk-pixbuf Library
<<< Previous Page | Home | Up | Next Page >>>

# Scaling

## Name

Scaling -- Scaling pixbufs and scaling and compositing pixbufs

## Synopsis

    #include <gdk-pixbuf/gdk-pixbuf.h>

    enum        GdkInterpType;
    GdkPixbuf*  gdk_pixbuf_scale_simple         (const GdkPixbuf *src,
                                                 int dest_width,
                                                 int dest_height,
                                                 GdkInterpType interp_type);
    void        gdk_pixbuf_scale                (const GdkPixbuf *src,
                                                 GdkPixbuf *dest,
                                                 int dest_x,
                                                 int dest_y,
                                                 int dest_width,
                                                 int dest_height,
                                                 double offset_x,
                                                 double offset_y,
                                                 double scale_x,
                                                 double scale_y,
                                                 GdkInterpType interp_type);
    GdkPixbuf*  gdk_pixbuf_composite_color_simple
                                                (const GdkPixbuf *src,
                                                 int dest_width,
                                                 int dest_height,
                                                 GdkInterpType interp_type,
                                                 int overall_alpha,
                                                 int check_size,
                                                 guint32 color1,
                                                 guint32 color2);
    void        gdk_pixbuf_composite            (const GdkPixbuf *src,
                                                 GdkPixbuf *dest,
                                                 int dest_x,
                                                 int dest_y,
                                                 int dest_width,
                                                 int dest_height,
                                                 double offset_x,
                                                 double offset_y,
                                                 double scale_x,
                                                 double scale_y,
                                                 GdkInterpType interp_type,
                                                 int overall_alpha);
    void        gdk_pixbuf_composite_color      (const GdkPixbuf *src,
                                                 GdkPixbuf *dest,
                                                 int dest_x,
                                                 int dest_y,
                                                 int dest_width,
                                                 int dest_height,
                                                 double offset_x,
                                                 double offset_y,
                                                 double scale_x,
                                                 double scale_y,
                                                 GdkInterpType interp_type,
                                                 int overall_alpha,
                                                 int check_x,
                                                 int check_y,
                                                 int check_size,
                                                 guint32 color1,
                                                 guint32 color2);

## Description

The gdk-pixbuf contains functions to scale pixbufs, to scale pixbufs and composite against an existing image, and to scale pixbufs and composite against a solid color or checkerboard. Compositing a checkerboard is a common way to show an image with an alpha channel in image-viewing and editing software.

Since the full-featured functions (gdk_pixbuf_scale(), gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are rather complex to use and have many arguments, two simple convenience functions are provided, gdk_pixbuf_scale_simple() and gdk_pixbuf_composite_color_simple() which create a new pixbuf of a given size, scale an original image to fit, and then return the new pixbuf.

The following example demonstrates handling an expose event by rendering the appropriate area of a source image (which is scaled to fit the widget) onto the widget's window. The source image is rendered against a checkerboard, which provides a visual representation of the alpha channel if the image has one. If the image doesn't have an alpha channel, calling gdk_pixbuf_composite_color() function has exactly the same effect as calling gdk_pixbuf_scale().

Example 1. Handling an expose event.

    gboolean
    expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
    {
      GdkPixbuf *dest;

      gdk_window_set_back_pixmap (widget->window, NULL, FALSE);

      dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height);

      gdk_pixbuf_composite_color (pixbuf, dest,
                                  0, 0, event->area.width, event->area.height,
                                  -event->area.x, -event->area.y,
                                  (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf),
                                  (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf),
                                  GDK_INTERP_BILINEAR, 255,
                                  event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);

      gdk_pixbuf_render_to_drawable (dest, widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
                                     0, 0, event->area.x, event->area.y,
                                     event->area.width, event->area.height,
                                     GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y);

      gdk_pixbuf_unref (dest);

      return TRUE;
    }

## Details

### enum GdkInterpType

    typedef enum {
    	GDK_INTERP_NEAREST,
    	GDK_INTERP_TILES,
    	GDK_INTERP_BILINEAR,
    	GDK_INTERP_HYPER
    } GdkInterpType;

This enumeration describes the different interpolation modes that can be used with the scaling functions. `GDK_INTERP_NEAREST` is the fastest scaling method, but has horrible quality when scaling down. `GDK_INTERP_BILINEAR` is the best choice if you aren't sure what to choose, it has a good speed/quality balance.

> Note: Cubic filtering is missing from the list; hyperbolic interpolation is just as fast and results in higher quality.

`GDK_INTERP_NEAREST` | Nearest neighbor sampling; this is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be OK when scaling up.
`GDK_INTERP_TILES` | This is an accurate simulation of the PostScript image operator without any interpolation enabled. Each pixel is rendered as a tiny parallelogram of solid color, the edges of which are implemented with antialiasing. It resembles nearest neighbor for enlargement, and bilinear for reduction.
`GDK_INTERP_BILINEAR` | Best quality/speed balance; use this mode by default. Bilinear interpolation. For enlargement, it is equivalent to point-sampling the ideal bilinear-interpolated image. For reduction, it is equivalent to laying down small tiles and integrating over the coverage area.
`GDK_INTERP_HYPER` | This is the slowest and highest quality reconstruction function. It is derived from the hyperbolic filters in Wolberg's "Digital Image Warping", and is formally defined as the hyperbolic-filter sampling the ideal hyperbolic-filter interpolated image (the filter is designed to be idempotent for 1:1 pixel mapping).

### gdk_pixbuf_scale_simple ()

    GdkPixbuf*  gdk_pixbuf_scale_simple         (const GdkPixbuf *src,
                                                 int dest_width,
                                                 int dest_height,
                                                 GdkInterpType interp_type);

Create a new GdkPixbuf containing a copy of `src` scaled to `dest_width` x `dest_height`. Leaves `src` unaffected. `interp_type` should be GDK_INTERP_NEAREST if you want maximum speed (but when scaling down GDK_INTERP_NEAREST is usually unusably ugly). The default `interp_type` should be GDK_INTERP_BILINEAR which offers reasonable quality and speed.

You can scale a sub-portion of `src` by creating a sub-pixbuf pointing into `src`; see gdk_pixbuf_new_subpixbuf().

For more complicated scaling/compositing see gdk_pixbuf_scale() and gdk_pixbuf_composite().

`src` : | a GdkPixbuf
`dest_width` : | the width of destination image
`dest_height` : | the height of destination image
`interp_type` : | the interpolation type for the transformation.
Returns : | the new GdkPixbuf, or `NULL` if not enough memory could be allocated for it.

### gdk_pixbuf_scale ()

    void        gdk_pixbuf_scale                (const GdkPixbuf *src,
                                                 GdkPixbuf *dest,
                                                 int dest_x,
                                                 int dest_y,
                                                 int dest_width,
                                                 int dest_height,
                                                 double offset_x,
                                                 double offset_y,
                                                 double scale_x,
                                                 double scale_y,
                                                 GdkInterpType interp_type);

Creates a transformation of the source image `src` by scaling by `scale_x` and `scale_y` then translating by `offset_x` and `offset_y`, then renders the rectangle (`dest_x`, `dest_y`, `dest_width`, `dest_height`) of the resulting image onto the destination image replacing the previous contents.

Try to use gdk_pixbuf_scale_simple() first, this function is the industrial-strength power tool you can fall back to if gdk_pixbuf_scale_simple() isn't powerful enough.

`src` : | a GdkPixbuf
`dest` : | the GdkPixbuf into which to render the results
`dest_x` : | the left coordinate for region to render
`dest_y` : | the top coordinate for region to render
`dest_width` : | the width of the region to render
`dest_height` : | the height of the region to render
`offset_x` : | the offset in the X direction (currently rounded to an integer)
`offset_y` : | the offset in the Y direction (currently rounded to an integer)
`scale_x` : | the scale factor in the X direction
`scale_y` : | the scale factor in the Y direction
`interp_type` : | the interpolation type for the transformation.

### gdk_pixbuf_composite_color_simple ()

    GdkPixbuf*  gdk_pixbuf_composite_color_simple
                                                (const GdkPixbuf *src,
                                                 int dest_width,
                                                 int dest_height,
                                                 GdkInterpType interp_type,
                                                 int overall_alpha,
                                                 int check_size,
                                                 guint32 color1,
                                                 guint32 color2);

Creates a new GdkPixbuf by scaling `src` to `dest_width` x `dest_height` and compositing the result with a checkboard of colors `color1` and `color2`.

`src` : | a GdkPixbuf
`dest_width` : | the width of destination image
`dest_height` : | the height of destination image
`interp_type` : | the interpolation type for the transformation.
`overall_alpha` : | overall alpha for source image (0..255)
`check_size` : | the size of checks in the checkboard (must be a power of two)
`color1` : | the color of check at upper left
`color2` : | the color of the other check
Returns : | the new GdkPixbuf, or `NULL` if not enough memory could be allocated for it.

### gdk_pixbuf_composite ()

    void        gdk_pixbuf_composite            (const GdkPixbuf *src,
                                                 GdkPixbuf *dest,
                                                 int dest_x,
                                                 int dest_y,
                                                 int dest_width,
                                                 int dest_height,
                                                 double offset_x,
                                                 double offset_y,
                                                 double scale_x,
                                                 double scale_y,
                                                 GdkInterpType interp_type,
                                                 int overall_alpha);

Creates a transformation of the source image `src` by scaling by `scale_x` and `scale_y` then translating by `offset_x` and `offset_y`, then composites the rectangle (`dest_x`, `dest_y`, `dest_width`, `dest_height`) of the resulting image onto the destination image.

`src` : | a GdkPixbuf
`dest` : | the GdkPixbuf into which to render the results
`dest_x` : | the left coordinate for region to render
`dest_y` : | the top coordinate for region to render
`dest_width` : | the width of the region to render
`dest_height` : | the height of the region to render
`offset_x` : | the offset in the X direction (currently rounded to an integer)
`offset_y` : | the offset in the Y direction (currently rounded to an integer)
`scale_x` : | the scale factor in the X direction
`scale_y` : | the scale factor in the Y direction
`interp_type` : | the interpolation type for the transformation.
`overall_alpha` : | overall alpha for source image (0..255)

### gdk_pixbuf_composite_color ()

    void        gdk_pixbuf_composite_color      (const GdkPixbuf *src,
                                                 GdkPixbuf *dest,
                                                 int dest_x,
                                                 int dest_y,
                                                 int dest_width,
                                                 int dest_height,
                                                 double offset_x,
                                                 double offset_y,
                                                 double scale_x,
                                                 double scale_y,
                                                 GdkInterpType interp_type,
                                                 int overall_alpha,
                                                 int check_x,
                                                 int check_y,
                                                 int check_size,
                                                 guint32 color1,
                                                 guint32 color2);

Creates a transformation of the source image `src` by scaling by `scale_x` and `scale_y` then translating by `offset_x` and `offset_y`, then composites the rectangle (`dest_x` ,`dest_y`, `dest_width`, `dest_height`) of the resulting image with a checkboard of the colors `color1` and `color2` and renders it onto the destination image.

See gdk_pixbuf_composite_color_simple() for a simpler variant of this function suitable for many tasks.

`src` : | a GdkPixbuf
`dest` : | the GdkPixbuf into which to render the results
`dest_x` : | the left coordinate for region to render
`dest_y` : | the top coordinate for region to render
`dest_width` : | the width of the region to render
`dest_height` : | the height of the region to render
`offset_x` : | the offset in the X direction (currently rounded to an integer)
`offset_y` : | the offset in the Y direction (currently rounded to an integer)
`scale_x` : | the scale factor in the X direction
`scale_y` : | the scale factor in the Y direction
`interp_type` : | the interpolation type for the transformation.
`overall_alpha` : | overall alpha for source image (0..255)
`check_x` : | the X offset for the checkboard (origin of checkboard is at -`check_x`, -`check_y`)
`check_y` : | the Y offset for the checkboard
`check_size` : | the size of checks in the checkboard (must be a power of two)
`color1` : | the color of check at upper left
`color2` : | the color of the other check

## See Also

GdkRGB.

<<< Previous Page | Home | Up | Next Page >>>
Inline data | Rendering