Scaling

Scaling — Scaling pixbufs and scaling and alpha blending pixbufs

Functions

Types and Values

Includes

#include <gdk-pixbuf/gdk-pixbuf.h>

Description

The GdkPixBuf contains functions to scale pixbufs, to scale pixbufs and alpha blend against an existing image, and to scale pixbufs and alpha blend against a solid color or checkerboard. Alpha blending a checkerboard is a common way to show an image with an alpha channel in image-viewing and editing software.

Note that in these functions, the terms ‘alpha blending’ and ‘compositing’ are used synonymously.

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.

If the destination pixbuf was created from a readonly source, these operations will force a copy into a mutable buffer.

Scaling and alpha blending 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.

The alpha blending function used is:

1
Cd = Cs·As + Cd(1-As)

where Cd is the destination pixel color, Cs is the source pixel color, and As is the source pixel alpha.

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().

Handling an expose event

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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;
}

Functions

gdk_pixbuf_scale_simple ()

GdkPixbuf *
gdk_pixbuf_scale_simple (const GdkPixbuf *src,
                         int dest_width,
                         int dest_height,
                         GdkInterpType interp_type);

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().

If dest_width and dest_height are equal to the src width and height, a copy of src is returned, avoiding any scaling.

For more complicated scaling/alpha blending see gdk_pixbuf_scale() and gdk_pixbuf_composite().

Parameters

src

a GdkPixbuf

 

dest_width

the width of destination image

 

dest_height

the height of destination image

 

interp_type

the interpolation type for the transformation.

 

Returns

the new GdkPixbuf, or NULL if not enough memory could be allocated for it.

[transfer full]


gdk_pixbuf_scale ()

void
gdk_pixbuf_scale (const GdkPixbuf *src,
                  GdkPixbuf *dest,
                  int dest_x,
                  int dest_y,
                  int dest_width,
                  int dest_height,
                  double offset_x,
                  double offset_y,
                  double scale_x,
                  double scale_y,
                  GdkInterpType interp_type);

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.

If the source rectangle overlaps the destination rectangle on the same pixbuf, it will be overwritten during the scaling which results in rendering artifacts.

Parameters

src

a GdkPixbuf

 

dest

the GdkPixbuf into which to render the results

 

dest_x

the left coordinate for region to render

 

dest_y

the top coordinate for region to render

 

dest_width

the width of the region to render

 

dest_height

the height of the region to render

 

offset_x

the offset in the X direction (currently rounded to an integer)

 

offset_y

the offset in the Y direction (currently rounded to an integer)

 

scale_x

the scale factor in the X direction

 

scale_y

the scale factor in the Y direction

 

interp_type

the interpolation type for the transformation.

 

gdk_pixbuf_composite_color_simple ()

GdkPixbuf *
gdk_pixbuf_composite_color_simple (const GdkPixbuf *src,
                                   int dest_width,
                                   int dest_height,
                                   GdkInterpType interp_type,
                                   int overall_alpha,
                                   int check_size,
                                   guint32 color1,
                                   guint32 color2);

Creates a new GdkPixbuf by scaling src to dest_width x dest_height and alpha blending the result with a checkboard of colors color1 and color2 .

Parameters

src

a GdkPixbuf

 

dest_width

the width of destination image

 

dest_height

the height of destination image

 

interp_type

the interpolation type for the transformation.

 

overall_alpha

overall alpha for source image (0..255)

 

check_size

the size of checks in the checkboard (must be a power of two)

 

color1

the color of check at upper left

 

color2

the color of the other check

 

Returns

the new GdkPixbuf, or NULL if not enough memory could be allocated for it.

[transfer full]


gdk_pixbuf_composite ()

void
gdk_pixbuf_composite (const GdkPixbuf *src,
                      GdkPixbuf *dest,
                      int dest_x,
                      int dest_y,
                      int dest_width,
                      int dest_height,
                      double offset_x,
                      double offset_y,
                      double scale_x,
                      double scale_y,
                      GdkInterpType interp_type,
                      int overall_alpha);

Creates a transformation of the source image src by scaling by scale_x and scale_y then translating by offset_x and offset_y . This gives an image in the coordinates of the destination pixbuf. The rectangle (dest_x , dest_y , dest_width , dest_height ) is then alpha blended onto the corresponding rectangle of the original destination image.

When the destination rectangle contains parts not in the source image, the data at the edges of the source image is replicated to infinity.

Parameters

src

a GdkPixbuf

 

dest

the GdkPixbuf into which to render the results

 

dest_x

the left coordinate for region to render

 

dest_y

the top coordinate for region to render

 

dest_width

the width of the region to render

 

dest_height

the height of the region to render

 

offset_x

the offset in the X direction (currently rounded to an integer)

 

offset_y

the offset in the Y direction (currently rounded to an integer)

 

scale_x

the scale factor in the X direction

 

scale_y

the scale factor in the Y direction

 

interp_type

the interpolation type for the transformation.

 

overall_alpha

overall alpha for source image (0..255)

 

gdk_pixbuf_composite_color ()

void
gdk_pixbuf_composite_color (const GdkPixbuf *src,
                            GdkPixbuf *dest,
                            int dest_x,
                            int dest_y,
                            int dest_width,
                            int dest_height,
                            double offset_x,
                            double offset_y,
                            double scale_x,
                            double scale_y,
                            GdkInterpType interp_type,
                            int overall_alpha,
                            int check_x,
                            int check_y,
                            int check_size,
                            guint32 color1,
                            guint32 color2);

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 alpha blends 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.

If the source image has no alpha channel, and overall_alpha is 255, a fast path is used which omits the alpha blending and just performs the scaling.

See gdk_pixbuf_composite_color_simple() for a simpler variant of this function suitable for many tasks.

Parameters

src

a GdkPixbuf

 

dest

the GdkPixbuf into which to render the results

 

dest_x

the left coordinate for region to render

 

dest_y

the top coordinate for region to render

 

dest_width

the width of the region to render

 

dest_height

the height of the region to render

 

offset_x

the offset in the X direction (currently rounded to an integer)

 

offset_y

the offset in the Y direction (currently rounded to an integer)

 

scale_x

the scale factor in the X direction

 

scale_y

the scale factor in the Y direction

 

interp_type

the interpolation type for the transformation.

 

overall_alpha

overall alpha for source image (0..255)

 

check_x

the X offset for the checkboard (origin of checkboard is at -check_x , -check_y )

 

check_y

the Y offset for the checkboard

 

check_size

the size of checks in the checkboard (must be a power of two)

 

color1

the color of check at upper left

 

color2

the color of the other check

 

gdk_pixbuf_rotate_simple ()

GdkPixbuf *
gdk_pixbuf_rotate_simple (const GdkPixbuf *src,
                          GdkPixbufRotation angle);

Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf.

If angle is 0, a copy of src is returned, avoiding any rotation.

Parameters

src

a GdkPixbuf

 

angle

the angle to rotate by

 

Returns

the new GdkPixbuf, or NULL if not enough memory could be allocated for it.

[nullable][transfer full]

Since: 2.6


gdk_pixbuf_flip ()

GdkPixbuf *
gdk_pixbuf_flip (const GdkPixbuf *src,
                 gboolean horizontal);

Flips a pixbuf horizontally or vertically and returns the result in a new pixbuf.

Parameters

src

a GdkPixbuf

 

horizontal

TRUE to flip horizontally, FALSE to flip vertically

 

Returns

the new GdkPixbuf, or NULL if not enough memory could be allocated for it.

[nullable][transfer full]

Since: 2.6

Types and Values

enum GdkInterpType

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> Cubic filtering is missing from the list; hyperbolic interpolation is just as fast and results in higher quality. </note>

Members

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).

 

enum GdkPixbufRotation

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.

Members

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.

 

See Also

<link linkend="gdk-GdkRGB">GdkRGB</link>.