Scaling
Scaling — Scaling pixbufs and scaling and compositing pixbufs
|
|
Synopsis
#include <gdk-pixbuf/gdk-pixbuf.h>
enum GdkInterpType;
GdkPixbuf* gdk_pixbuf_scale_simple (const GdkPixbuf *src,
int dest_width,
int dest_height,
GdkInterpType interp_type);
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);
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);
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);
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);
enum GdkPixbufRotation;
GdkPixbuf* gdk_pixbuf_rotate_simple (const GdkPixbuf *src,
GdkPixbufRotation angle);
GdkPixbuf* gdk_pixbuf_flip (const GdkPixbuf *src,
gboolean horizontal);
Description
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.
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.
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.
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() .
Example 2. Handling an expose event.
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;
}
Details
enum GdkInterpType
typedef enum {
GDK_INTERP_NEAREST,
GDK_INTERP_TILES,
GDK_INTERP_BILINEAR,
GDK_INTERP_HYPER
} 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.
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).
|
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() .
For more complicated scaling/compositing see gdk_pixbuf_scale()
and gdk_pixbuf_composite() .
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.
|
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.
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 compositing the result with a checkboard of colors
color1 and color2 .
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.
|
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 composited 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.
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 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.
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
|
enum GdkPixbufRotation
typedef enum {
GDK_PIXBUF_ROTATE_NONE = 0,
GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE = 90,
GDK_PIXBUF_ROTATE_UPSIDEDOWN = 180,
GDK_PIXBUF_ROTATE_CLOCKWISE = 270
} 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.
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.
|
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.
src :
|
a GdkPixbuf
|
angle :
|
the angle to rotate by
|
Returns : |
the new GdkPixbuf, or NULL if not enough memory could be
allocated for it.
|
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.
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.
|
Since 2.6
|