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