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_INTERP_NEARESTNearest neighbor sampling; this is the fastest and lowest quality mode.
GDK_INTERP_TILESThis 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_BILINEARBilinear 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_HYPERThis 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 ()

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

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


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

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

See Also

GdkRGB