<!-- ##### SECTION Title ##### -->
-scaling
+Scaling
<!-- ##### SECTION Short_Description ##### -->
-
+Scaling pixbufs and scaling and compositing pixbufs
<!-- ##### SECTION Long_Description ##### -->
-<para>
+ <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>
-</para>
+<!-- ##### SECTION See_Also ##### -->
+ <para>
+ <link linkend="gdk-GdkRGB">GdkRGB</link>.
+ </para>
+<!-- ##### SECTION Stability_Level ##### -->
-<!-- ##### SECTION See_Also ##### -->
-<para>
-</para>
+<!-- ##### SECTION Image ##### -->
<!-- ##### 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>
-@GDK_INTERP_NEAREST:
-@GDK_INTERP_TILES:
-@GDK_INTERP_BILINEAR:
-@GDK_INTERP_HYPER:
+@src:
+@dest_width:
+@dest_height:
+@interp_type:
+@Returns:
+
<!-- ##### FUNCTION gdk_pixbuf_scale ##### -->
<para>
@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>
@color2:
-<!-- ##### FUNCTION gdk_pixbuf_scale_simple ##### -->
+<!-- ##### 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:
-@dest_width:
-@dest_height:
-@interp_type:
+@angle:
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_composite_color_simple ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_flip ##### -->
<para>
</para>
@src:
-@dest_width:
-@dest_height:
-@interp_type:
-@overall_alpha:
-@check_size:
-@color1:
-@color2:
+@horizontal:
@Returns:
projects / ~andy / gtk / blobdiff