Pileus Git - ~andy/gtk/blob - docs/reference/gdk-pixbuf/tmpl/scaling.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Scaling
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Scaling pixbufs and scaling and compositing pixbufs
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8   <para>
   9     The &gdk-pixbuf; contains functions to scale pixbufs, to scale
  10     pixbufs and composite against an existing image, and to scale
  11     pixbufs and composite against a solid color or checkerboard.
  12     Compositing a checkerboard is a common way to show an image with
  13     an alpha channel in image-viewing and editing software.
  14   </para>
  15
  16   <para>
  17     Since the full-featured functions (gdk_pixbuf_scale(),
  18     gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are
  19     rather complex to use and have many arguments, two simple
  20     convenience functions are provided, gdk_pixbuf_scale_simple() and
  21     gdk_pixbuf_composite_color_simple() which create a new pixbuf of a
  22     given size, scale an original image to fit, and then return the
  23     new pixbuf.
  24   </para>
  25
  26   <para>
  27    Scaling and compositing functions take advantage of MMX hardware
  28    acceleration on systems where MMX is supported.  If gdk-pixbuf is built
  29    with the Sun mediaLib library, these functions are instead accelerated
  30    using mediaLib, which provides hardware acceleration on Intel, AMD,
  31    and Sparc chipsets.  If desired, mediaLib support can be turned off by
  32    setting the GDK_DISABLE_MEDIALIB environment variable.
  33   </para>
  34
  35   <para>
  36     The following example demonstrates handling an expose event by
  37     rendering the appropriate area of a source image (which is scaled
  38     to fit the widget) onto the widget's window.  The source image is
  39     rendered against a checkerboard, which provides a visual
  40     representation of the alpha channel if the image has one. If the
  41     image doesn't have an alpha channel, calling
  42     gdk_pixbuf_composite_color() function has exactly the same effect
  43     as calling gdk_pixbuf_scale().
  44   </para>
  45
  46   <example>
  47   <title>Handling an expose event.</title>
  48   <programlisting>
  49 gboolean
  50 expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
  51 {
  52   GdkPixbuf *dest;
  53
  54   dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height);
  55
  56   gdk_pixbuf_composite_color (pixbuf, dest,
  57                               0, 0, event->area.width, event->area.height,
  58                               -event->area.x, -event->area.y,
  59                               (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf),
  60                               (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf),
  61                               GDK_INTERP_BILINEAR, 255,
  62                               event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);
  63
  64   gdk_draw_pixbuf (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL], dest,
  65                    0, 0, event->area.x, event->area.y,
  66                    event->area.width, event->area.height,
  67                    GDK_RGB_DITHER_NORMAL, event->area.x, event->area.y);
  68
  69   gdk_pixbuf_unref (dest);
  70
  71   return TRUE;
  72 }
  73   </programlisting>
  74   </example>
  75
  76 <!-- ##### SECTION See_Also ##### -->
  77   <para>
  78     <link linkend="gdk-GdkRGB">GdkRGB</link>.
  79   </para>
  80
  81 <!-- ##### SECTION Stability_Level ##### -->
  82
  83
  84 <!-- ##### ENUM GdkInterpType ##### -->
  85   <para>
  86     This enumeration describes the different interpolation modes that
  87     can be used with the scaling functions. @GDK_INTERP_NEAREST is
  88     the fastest scaling method, but has horrible quality when
  89     scaling down. @GDK_INTERP_BILINEAR is the best choice if you
  90     aren't sure what to choose, it has a good speed/quality balance.
  91
  92     <note>
  93       <para>
  94         Cubic filtering is missing from the list; hyperbolic
  95         interpolation is just as fast and results in higher quality.
  96       </para>
  97     </note>
  98   </para>
  99
 100 @GDK_INTERP_NEAREST: Nearest neighbor sampling; this is the fastest
 101 and lowest quality mode. Quality is normally unacceptable when scaling
 102 down, but may be OK when scaling up.
 103 @GDK_INTERP_TILES: This is an accurate simulation of the PostScript
 104 image operator without any interpolation enabled.  Each pixel is
 105 rendered as a tiny parallelogram of solid color, the edges of which
 106 are implemented with antialiasing.  It resembles nearest neighbor for
 107 enlargement, and bilinear for reduction.
 108 @GDK_INTERP_BILINEAR: Best quality/speed balance; use this mode by
 109 default. Bilinear interpolation.  For enlargement, it is
 110 equivalent to point-sampling the ideal bilinear-interpolated image.
 111 For reduction, it is equivalent to laying down small tiles and
 112 integrating over the coverage area.
 113 @GDK_INTERP_HYPER: This is the slowest and highest quality
 114 reconstruction function. It is derived from the hyperbolic filters in
 115 Wolberg's "Digital Image Warping", and is formally defined as the
 116 hyperbolic-filter sampling the ideal hyperbolic-filter interpolated
 117 image (the filter is designed to be idempotent for 1:1 pixel mapping).
 118
 119 <!-- ##### FUNCTION gdk_pixbuf_scale_simple ##### -->
 120 <para>
 121
 122 </para>
 123
 124 @src:
 125 @dest_width:
 126 @dest_height:
 127 @interp_type:
 128 @Returns:
 129
 130
 131 <!-- ##### FUNCTION gdk_pixbuf_scale ##### -->
 132 <para>
 133
 134 </para>
 135
 136 @src:
 137 @dest:
 138 @dest_x:
 139 @dest_y:
 140 @dest_width:
 141 @dest_height:
 142 @offset_x:
 143 @offset_y:
 144 @scale_x:
 145 @scale_y:
 146 @interp_type:
 147
 148
 149 <!-- ##### FUNCTION gdk_pixbuf_composite_color_simple ##### -->
 150 <para>
 151
 152 </para>
 153
 154 @src:
 155 @dest_width:
 156 @dest_height:
 157 @interp_type:
 158 @overall_alpha:
 159 @check_size:
 160 @color1:
 161 @color2:
 162 @Returns: <!--
 163 Local variables:
 164 mode: sgml
 165 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 166 End:
 167 -->
 168
 169
 170 <!-- ##### FUNCTION gdk_pixbuf_composite ##### -->
 171 <para>
 172
 173 </para>
 174
 175 @src:
 176 @dest:
 177 @dest_x:
 178 @dest_y:
 179 @dest_width:
 180 @dest_height:
 181 @offset_x:
 182 @offset_y:
 183 @scale_x:
 184 @scale_y:
 185 @interp_type:
 186 @overall_alpha:
 187
 188
 189 <!-- ##### FUNCTION gdk_pixbuf_composite_color ##### -->
 190 <para>
 191
 192 </para>
 193
 194 @src:
 195 @dest:
 196 @dest_x:
 197 @dest_y:
 198 @dest_width:
 199 @dest_height:
 200 @offset_x:
 201 @offset_y:
 202 @scale_x:
 203 @scale_y:
 204 @interp_type:
 205 @overall_alpha:
 206 @check_x:
 207 @check_y:
 208 @check_size:
 209 @color1:
 210 @color2:
 211
 212
 213 <!-- ##### ENUM GdkPixbufRotation ##### -->
 214 <para>
 215 The possible rotations which can be passed to gdk_pixbuf_rotate_simple().
 216 To make them easier to use, their numerical values are the actual degrees.
 217 </para>
 218
 219 @GDK_PIXBUF_ROTATE_NONE: No rotation.
 220 @GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE: Rotate by 90 degrees.
 221 @GDK_PIXBUF_ROTATE_UPSIDEDOWN: Rotate by 180 degrees.
 222 @GDK_PIXBUF_ROTATE_CLOCKWISE: Rotate by 270 degrees.
 223
 224 <!-- ##### FUNCTION gdk_pixbuf_rotate_simple ##### -->
 225 <para>
 226
 227 </para>
 228
 229 @src:
 230 @angle:
 231 @Returns:
 232
 233
 234 <!-- ##### FUNCTION gdk_pixbuf_flip ##### -->
 235 <para>
 236
 237 </para>
 238
 239 @src:
 240 @horizontal:
 241 @Returns:
 242
 243