Next: , Previous: Image Data in Memory, Up: Top

32 Scaling

Scaling pixbufs and scaling and compositing pixbufs

32.1 Overview

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. 

     
     gboolean
     expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
     {
       GdkPixbuf *dest;
     
       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;
     }

32.2 Usage

— Function: gdk-pixbuf-scale-simple (self <gdk-pixbuf>) (dest_width int) (dest_height int) (interp_type <gdk-interp-type>) ⇒  (ret <gdk-pixbuf>)
— Method: scale-simple

Create a new <gdk-pixbuf> 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 <gdk-pixbuf>
dest-width
the width of destination image
dest-height
the height of destination image
interp-type
the interpolation type for the transformation.
ret
the new <gdk-pixbuf>, or ‘#f’ if not enough memory could be allocated for it.
— Function: gdk-pixbuf-scale (self <gdk-pixbuf>) (dest <gdk-pixbuf>) (dest_x int) (dest_y int) (dest_width int) (dest_height int) (offset_x double) (offset_y double) (scale_x double) (scale_y double) (interp_type <gdk-interp-type>)
— Method: scale

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 <gdk-pixbuf>
dest
the <gdk-pixbuf> 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.
— Function: gdk-pixbuf-composite-color-simple (self <gdk-pixbuf>) (dest_width int) (dest_height int) (interp_type <gdk-interp-type>) (overall_alpha int) (check_size int) (color1 unsigned-int32) (color2 unsigned-int32) ⇒  (ret <gdk-pixbuf>)
— Method: composite-color-simple

Creates a new <gdk-pixbuf> by scaling src to dest-width x dest-height and compositing the result with a checkboard of colors color1 and color2.

src
a <gdk-pixbuf>
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
ret
the new <gdk-pixbuf>, or ‘#f’ if not enough memory could be allocated for it.
— Function: gdk-pixbuf-composite (self <gdk-pixbuf>) (dest <gdk-pixbuf>) (dest_x int) (dest_y int) (dest_width int) (dest_height int) (offset_x double) (offset_y double) (scale_x double) (scale_y double) (interp_type <gdk-interp-type>) (overall_alpha int)
— Method: composite

Creates a transformation of the source image src by scaling by scale-x and scale-y then translating by offset-x and offset-y. This gives an image in the coordinates of the destination pixbuf. The rectangle (dest-x, dest-y, dest-width, dest-height) is then composited onto the corresponding rectangle of the original destination image.

When the destination rectangle contains parts not in the source image, the data at the edges of the source image is replicated to infinity.

(The missing figure, pixbuf-composite-diagram

src
a <gdk-pixbuf>
dest
the <gdk-pixbuf> 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)
— Function: gdk-pixbuf-composite-color (self <gdk-pixbuf>) (dest <gdk-pixbuf>) (dest_x int) (dest_y int) (dest_width int) (dest_height int) (offset_x double) (offset_y double) (scale_x double) (scale_y double) (interp_type <gdk-interp-type>) (overall_alpha int) (check_x int) (check_y int) (check_size int) (color1 unsigned-int32) (color2 unsigned-int32)
— Method: composite-color

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 <gdk-pixbuf>
dest
the <gdk-pixbuf> 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
— Function: gdk-pixbuf-rotate-simple (self <gdk-pixbuf>) (angle <gdk-pixbuf-rotation>) ⇒  (ret <gdk-pixbuf>)
— Method: rotate-simple

Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf.

src
a <gdk-pixbuf>
angle
the angle to rotate by
ret
a new pixbuf

Since 2.6

— Function: gdk-pixbuf-flip (self <gdk-pixbuf>) (horizontal bool) ⇒  (ret <gdk-pixbuf>)
— Method: flip

Flips a pixbuf horizontally or vertically and returns the result in a new pixbuf.

src
a <gdk-pixbuf>
horizontal
‘#t’ to flip horizontally, ‘#f’ to flip vertically
ret
a new pixbuf.

Since 2.6