gtk/docs/reference/gdk-pixbuf/tmpl/scaling.sgml

<!-- ##### SECTION Title ##### -->
Scaling

<!-- ##### SECTION Short_Description ##### -->
Scaling pixbufs and scaling and compositing pixbufs

<!-- ##### SECTION Long_Description ##### -->
  <para>
    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.
  </para>

  <para>
    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.
  </para>

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

  <example>
  <title>Handling an expose event.</title>
  <programlisting>
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;
}
  </programlisting>
  </example>

<!-- ##### SECTION See_Also ##### -->
  <para>
    <link linkend="gdk-GdkRGB">GdkRGB</link>.
  </para>

<!-- ##### ENUM GdkInterpType ##### -->
  <para>
    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>
      <para>
	Cubic filtering is missing from the list; hyperbolic
	interpolation is just as fast and results in higher quality.
      </para>
    </note>
  </para>

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

<!-- ##### FUNCTION gdk_pixbuf_scale ##### -->
<para>

</para>

@src: 
@dest: 
@dest_x: 
@dest_y: 
@dest_width: 
@dest_height: 
@offset_x: 
@offset_y: 
@scale_x: 
@scale_y: 
@interp_type: 


<!-- ##### FUNCTION gdk_pixbuf_composite ##### -->
<para>

</para>

@src: 
@dest: 
@dest_x: 
@dest_y: 
@dest_width: 
@dest_height: 
@offset_x: 
@offset_y: 
@scale_x: 
@scale_y: 
@interp_type: 
@overall_alpha: 


<!-- ##### FUNCTION gdk_pixbuf_composite_color ##### -->
<para>

</para>

@src: 
@dest: 
@dest_x: 
@dest_y: 
@dest_width: 
@dest_height: 
@offset_x: 
@offset_y: 
@scale_x: 
@scale_y: 
@interp_type: 
@overall_alpha: 
@check_x: 
@check_y: 
@check_size: 
@color1: 
@color2: 


<!-- ##### FUNCTION gdk_pixbuf_scale_simple ##### -->
<para>

</para>

@src: 
@dest_width: 
@dest_height: 
@interp_type: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_composite_color_simple ##### -->
<para>

</para>

@src: 
@dest_width: 
@dest_height: 
@interp_type: 
@overall_alpha: 
@check_size: 
@color1: 
@color2: 
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->