small doc tweaks, specifically some "just do XYZ" advice next to the

2001-12-16  Havoc Pennington  <hp@pobox.com>

	* gdk-pixbuf/tmpl/scaling.sgml: small doc tweaks, specifically
	some "just do XYZ" advice next to the InterpMode technojargon.

2001-12-16  Havoc Pennington  <hp@pobox.com>

	* gdk-pixbuf-scale.c: docs enhancements

docs/reference/ChangeLog

@@ -1,3 +1,8 @@
+2001-12-16  Havoc Pennington  <hp@pobox.com>
+
+	* gdk-pixbuf/tmpl/scaling.sgml: small doc tweaks, specifically
+	some "just do XYZ" advice next to the InterpMode technojargon.
+
 2001-12-16  Matthias Clasen  <matthiasc@poet.de>
 
 	* gdk/tmpl/windows.sgml: Add something about GdkModifierType.

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

@@ -20,7 +20,7 @@ Scaling pixbufs and scaling and compositing pixbufs
     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>
@@ -74,7 +74,10 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
 <!-- ##### 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>
@@ -85,18 +88,20 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
   </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).

gdk-pixbuf/ChangeLog

@@ -1,3 +1,7 @@
+2001-12-16  Havoc Pennington  <hp@pobox.com>
+
+	* gdk-pixbuf-scale.c: docs enhancements
+
 2001-12-14  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
 	* io-xpm.c: Use g_ascii_strcasecmp() instead of g_strcasecmp().

gdk-pixbuf/gdk-pixbuf-scale.c

@@ -41,11 +41,15 @@
  * @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
+ * Creates a transformation of the source image @src by scaling by
- * @scale_y then translating by @offset_x and @offset_y, then renders
+ * @scale_x and @scale_y then translating by @offset_x and @offset_y,
- * the rectangle (@dest_x, @dest_y, @dest_width, @dest_height) of the
+ * then renders the rectangle (@dest_x, @dest_y, @dest_width,
- * resulting image onto the destination image replacing the
+ * @dest_height) of the resulting image onto the destination image
- * previous contents.
+ * 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,
@@ -92,9 +96,9 @@ 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
+ * Creates a transformation of the source image @src by scaling by
- * @scale_y then translating by @offset_x and @offset_y, then
+ * @scale_x and @scale_y then translating by @offset_x and @offset_y,
- * composites the rectangle (@dest_x, @dest_y, @dest_width,
+ * then composites the rectangle (@dest_x, @dest_y, @dest_width,
  * @dest_height) of the resulting image onto the destination image.
  **/
 void
@@ -148,11 +152,16 @@ gdk_pixbuf_composite (const GdkPixbuf *src,
  * @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
+ * Creates a transformation of the source image @src by scaling by
- * translating by @offset_x and @offset_y, then composites the rectangle
+ * @scale_x and @scale_y then translating by @offset_x and @offset_y,
- * (@dest_x ,@dest_y, @dest_width, @dest_height) of the resulting image with
+ * then composites the rectangle (@dest_x ,@dest_y, @dest_width,
- * a checkboard of the colors @color1 and @color2 and renders it onto the
+ * @dest_height) of the resulting image with a checkboard of the
- * destination image.
+ * 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,
@@ -198,9 +207,19 @@ 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
+ * Create a new #GdkPixbuf containing a copy of @src scaled to
- * the result into a new #GdkPixbuf.
+ * @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.
@@ -240,9 +259,9 @@ gdk_pixbuf_scale_simple (const GdkPixbuf *src,
  * @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
+ * Creates a new #GdkPixbuf by scaling @src to @dest_width x
- * the result with a checkboard of colors @color1 and @color2 and
+ * @dest_height and compositing the result with a checkboard of colors
- * render the result into a new #GdkPixbuf.
+ * @color1 and @color2.
  * 
  * Return value: the new #GdkPixbuf, or NULL if not enough memory could be
  * allocated for it.