gtk/docs/reference/gdk-pixbuf/tmpl/scaling.sgml
2005-08-12 13:04:04 +00:00

235 lines
6.1 KiB
Plaintext

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