Scaling

Name

Scaling -- Scaling pixbufs and scaling and compositing pixbufs

Synopsis


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


enum        GdkInterpType;
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);
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);
GdkPixbuf*  gdk_pixbuf_scale_simple         (const GdkPixbuf *src,
                                             int dest_width,
                                             int dest_height,
                                             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);

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 pixmap.

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().

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.

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


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.


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.


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.


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.

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


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.

See Also

GdkRGB