diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 83b67c254d..7144b346cb 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +2001-12-16 Havoc Pennington + + * gdk-pixbuf/tmpl/scaling.sgml: small doc tweaks, specifically + some "just do XYZ" advice next to the InterpMode technojargon. + 2001-12-16 Matthias Clasen * gdk/tmpl/windows.sgml: Add something about GdkModifierType. diff --git a/docs/reference/gdk-pixbuf/tmpl/scaling.sgml b/docs/reference/gdk-pixbuf/tmpl/scaling.sgml index c3367f5cd5..bd7d13f45f 100644 --- a/docs/reference/gdk-pixbuf/tmpl/scaling.sgml +++ b/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. @@ -74,7 +74,10 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) 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. @@ -85,18 +88,20 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) @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). diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog index 50ad65b335..ec8fa85557 100644 --- a/gdk-pixbuf/ChangeLog +++ b/gdk-pixbuf/ChangeLog @@ -1,3 +1,7 @@ +2001-12-16 Havoc Pennington + + * gdk-pixbuf-scale.c: docs enhancements + 2001-12-14 Sebastian Wilhelmi * io-xpm.c: Use g_ascii_strcasecmp() instead of g_strcasecmp(). diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c index 355374b23a..1f2411e0f1 100644 --- a/gdk-pixbuf/gdk-pixbuf-scale.c +++ b/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 - * @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, @@ -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 - * @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 @@ -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 - * 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, @@ -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 - * 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. @@ -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 - * 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.