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 pixmap.
+ new pixbuf.
</para>
<para>
<!-- ##### ENUM GdkInterpType ##### -->
<para>
This enumeration describes the different interpolation modes that
- can be used with the scaling functions.
+ 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>
</para>
@GDK_INTERP_NEAREST: Nearest neighbor sampling; this is the fastest
-and lowest quality mode.
+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: Bilinear interpolation. For enlargement, it is
+@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
+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).
* @scale_y: the scale factor in the Y direction
* @interp_type: the interpolation type for the transformation.
*
- * Transforms the source image @src by scaling by @scale_x and
- * @scale_y then translating by @offset_x and @offset_y, then renders
- * the rectangle (@dest_x, @dest_y, @dest_width, @dest_height) of the
- * resulting image onto the destination image replacing the
- * previous contents.
+ * Creates a transformation of the source image @src by scaling by
+ * @scale_x and @scale_y then translating by @offset_x and @offset_y,
+ * then renders the rectangle (@dest_x, @dest_y, @dest_width,
+ * @dest_height) of the resulting image onto the destination image
+ * replacing the previous contents.
+ *
+ * Try to use gdk_pixbuf_scale_simple() first, this function is
+ * the industrial-strength power tool you can fall back to if
+ * gdk_pixbuf_scale_simple() isn't powerful enough.
**/
void
gdk_pixbuf_scale (const GdkPixbuf *src,
* @interp_type: the interpolation type for the transformation.
* @overall_alpha: overall alpha for source image (0..255)
*
- * Transforms the source image @src by scaling by @scale_x and
- * @scale_y then translating by @offset_x and @offset_y, then
- * composites the rectangle (@dest_x, @dest_y, @dest_width,
+ * Creates a transformation of the source image @src by scaling by
+ * @scale_x and @scale_y then translating by @offset_x and @offset_y,
+ * then composites the rectangle (@dest_x, @dest_y, @dest_width,
* @dest_height) of the resulting image onto the destination image.
**/
void
* @color1: the color of check at upper left
* @color2: the color of the other check
*
- * Transforms the source image @src by scaling by @scale_x and @scale_y then
- * translating by @offset_x and @offset_y, then composites the rectangle
- * (@dest_x ,@dest_y, @dest_width, @dest_height) of the resulting image with
- * a checkboard of the colors @color1 and @color2 and renders it onto the
- * destination image.
+ * Creates a transformation of the source image @src by scaling by
+ * @scale_x and @scale_y then translating by @offset_x and @offset_y,
+ * then composites the rectangle (@dest_x ,@dest_y, @dest_width,
+ * @dest_height) of the resulting image with a checkboard of the
+ * colors @color1 and @color2 and renders it onto the destination
+ * image.
+ *
+ * See gdk_pixbuf_composite_color_simple() for a simpler variant of this
+ * function suitable for many tasks.
+ *
**/
void
gdk_pixbuf_composite_color (const GdkPixbuf *src,
* @dest_width: the width of destination image
* @dest_height: the height of destination image
* @interp_type: the interpolation type for the transformation.
- *
- * Scale the #GdkPixbuf @src to @dest_width x @dest_height and render
- * the result into a new #GdkPixbuf.
+ *
+ * Create a new #GdkPixbuf containing a copy of @src scaled to
+ * @dest_width x @dest_height. Leaves @src unaffected. @interp_type
+ * should be #GDK_INTERP_NEAREST if you want maximum speed (but when
+ * scaling down #GDK_INTERP_NEAREST is usually unusably ugly). The
+ * default @interp_type should be #GDK_INTERP_BILINEAR which offers
+ * reasonable quality and speed.
+ *
+ * You can scale a sub-portion of @src by creating a sub-pixbuf
+ * pointing into @src; see gdk_pixbuf_new_subpixbuf().
+ *
+ * For more complicated scaling/compositing see gdk_pixbuf_scale()
+ * and gdk_pixbuf_composite().
*
* Return value: the new #GdkPixbuf, or NULL if not enough memory could be
* allocated for it.
* @color1: the color of check at upper left
* @color2: the color of the other check
*
- * Scale the #GdkPixbuf @src to @dest_width x @dest_height composite
- * the result with a checkboard of colors @color1 and @color2 and
- * render the result into a new #GdkPixbuf.
+ * Creates a new #GdkPixbuf by scaling @src to @dest_width x
+ * @dest_height and compositing the result with a checkboard of colors
+ * @color1 and @color2.
*
* Return value: the new #GdkPixbuf, or NULL if not enough memory could be
* allocated for it.
projects / ~andy / gtk / commitdiff