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>
   Scaling and compositing functions take advantage of MMX hardware
   acceleration on systems where MMX is supported.  If gdk-pixbuf is built
   with the Sun mediaLib library, these functions are instead accelerated
   using mediaLib, which provides hardware acceleration on Intel, AMD,
   and Sparc chipsets.  If desired, mediaLib support can be turned off by
   setting the GDK_DISABLE_MEDIALIB environment variable.  
  </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;

  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_draw_pixbuf (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL], dest,
                   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>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### 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_simple ##### -->
<para>

</para>

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


<!-- ##### 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_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:
-->


<!-- ##### 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: 


<!-- ##### ENUM GdkPixbufRotation ##### -->
<para>
The possible rotations which can be passed to gdk_pixbuf_rotate_simple().
To make them easier to use, their numerical values are the actual degrees.
</para>

@GDK_PIXBUF_ROTATE_NONE: No rotation.
@GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE: Rotate by 90 degrees.
@GDK_PIXBUF_ROTATE_UPSIDEDOWN: Rotate by 180 degrees.
@GDK_PIXBUF_ROTATE_CLOCKWISE: Rotate by 270 degrees.

<!-- ##### FUNCTION gdk_pixbuf_rotate_simple ##### -->
<para>

</para>

@src: 
@angle: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_flip ##### -->
<para>

</para>

@src: 
@horizontal: 
@Returns: