
@c %start of fragment

@node Scaling
@chapter Scaling
Scaling pixbufs and scaling and compositing pixbufs

@section 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 (@code{gdk-pixbuf-scale},
@code{gdk-pixbuf-composite}, and @code{gdk-pixbuf-composite-color}) are rather
complex to use and have many arguments, two simple convenience functions are
provided, @code{gdk-pixbuf-scale-simple} and
@code{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
@code{gdk-pixbuf-composite-color} function has exactly the same effect as
calling @code{gdk-pixbuf-scale}.

@example 

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;
@}
  
@end example

@section Usage
@include defuns-scaling.xml.texi

@c %end of fragment
