gdkdraw.c 55.2 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GDK - The GIMP Drawing Kit
Elliot Lee's avatar
Elliot Lee committed
2 3 4
 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
 *
 * This library is free software; you can redistribute it and/or
5
 * modify it under the terms of the GNU Lesser General Public
Elliot Lee's avatar
Elliot Lee committed
6 7 8 9 10 11
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12
 * Lesser General Public License for more details.
Elliot Lee's avatar
Elliot Lee committed
13
 *
14
 * You should have received a copy of the GNU Lesser General Public
15 16 17
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
Elliot Lee's avatar
Elliot Lee committed
18
 */
19 20

/*
21
 * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
22 23 24 25 26
 * file for a list of people on the GTK+ Team.  See the ChangeLog
 * files for a list of changes.  These files are distributed with
 * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
 */

27
#include "config.h"
28
#include <math.h>
29
#include <pango/pangocairo.h>
30
#include "gdkcairo.h"
Owen Taylor's avatar
Started  
Owen Taylor committed
31
#include "gdkdrawable.h"
32
#include "gdkinternals.h"
33
#include "gdkwindow.h"
34
#include "gdkscreen.h"
35 36
#include "gdk-pixbuf-private.h"
#include "gdkpixbuf.h"
37
#include "gdkalias.h"
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63

static GdkImage*    gdk_drawable_real_get_image (GdkDrawable     *drawable,
						 gint             x,
						 gint             y,
						 gint             width,
						 gint             height);
static GdkDrawable* gdk_drawable_real_get_composite_drawable (GdkDrawable  *drawable,
							      gint          x,
							      gint          y,
							      gint          width,
							      gint          height,
							      gint         *composite_x_offset,
							      gint         *composite_y_offset);
static GdkRegion *  gdk_drawable_real_get_visible_region     (GdkDrawable  *drawable);
static void         gdk_drawable_real_draw_pixbuf            (GdkDrawable  *drawable,
							      GdkGC        *gc,
							      GdkPixbuf    *pixbuf,
							      gint          src_x,
							      gint          src_y,
							      gint          dest_x,
							      gint          dest_y,
							      gint          width,
							      gint          height,
							      GdkRgbDither  dither,
							      gint          x_dither,
							      gint          y_dither);
64 65 66 67 68 69 70 71 72
static void         gdk_drawable_real_draw_drawable          (GdkDrawable  *drawable,
							      GdkGC	   *gc,
							      GdkDrawable  *src,
							      gint          xsrc,
							      gint	    ysrc,
							      gint	    xdest,
							      gint	    ydest,
							      gint	    width,
							      gint	    height);
73
     
Havoc Pennington's avatar
Havoc Pennington committed
74

Matthias Clasen's avatar
Matthias Clasen committed
75
G_DEFINE_ABSTRACT_TYPE (GdkDrawable, gdk_drawable, G_TYPE_OBJECT)
76

Havoc Pennington's avatar
Havoc Pennington committed
77 78 79
static void
gdk_drawable_class_init (GdkDrawableClass *klass)
{
80
  klass->get_image = gdk_drawable_real_get_image;
Havoc Pennington's avatar
Havoc Pennington committed
81
  klass->get_composite_drawable = gdk_drawable_real_get_composite_drawable;
82 83 84
  /* Default implementation for clip and visible region is the same */
  klass->get_clip_region = gdk_drawable_real_get_visible_region;
  klass->get_visible_region = gdk_drawable_real_get_visible_region;
85
  klass->draw_pixbuf = gdk_drawable_real_draw_pixbuf;
86
  klass->draw_drawable = gdk_drawable_real_draw_drawable;
Havoc Pennington's avatar
Havoc Pennington committed
87 88
}

Matthias Clasen's avatar
Matthias Clasen committed
89 90 91 92 93
static void
gdk_drawable_init (GdkDrawable *drawable)
{
}

94 95 96
/* Manipulation of drawables
 */

Havoc Pennington's avatar
Havoc Pennington committed
97 98 99 100 101
/**
 * gdk_drawable_set_data:
 * @drawable: a #GdkDrawable
 * @key: name to store the data under
 * @data: arbitrary data
Johan Dahlin's avatar
Johan Dahlin committed
102
 * @destroy_func: (allow-none): function to free @data, or %NULL
Havoc Pennington's avatar
Havoc Pennington committed
103 104 105 106 107
 *
 * This function is equivalent to g_object_set_data(),
 * the #GObject variant should be used instead.
 * 
 **/
108 109 110 111 112 113
void          
gdk_drawable_set_data (GdkDrawable   *drawable,
		       const gchar   *key,
		       gpointer	      data,
		       GDestroyNotify destroy_func)
{
114 115 116 117 118 119
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  
  g_object_set_qdata_full (G_OBJECT (drawable),
                           g_quark_from_string (key),
                           data,
                           destroy_func);
120 121
}

Havoc Pennington's avatar
Havoc Pennington committed
122 123 124 125 126 127 128 129 130 131
/**
 * gdk_drawable_get_data:
 * @drawable: a #GdkDrawable
 * @key: name the data was stored under
 * 
 * Equivalent to g_object_get_data(); the #GObject variant should be
 * used instead.
 * 
 * Return value: the data stored at @key
 **/
132
gpointer
133 134 135
gdk_drawable_get_data (GdkDrawable   *drawable,
		       const gchar   *key)
{
136
  g_return_val_if_fail (GDK_IS_DRAWABLE (drawable), NULL);
137
  
138 139
  return g_object_get_qdata (G_OBJECT (drawable),
                             g_quark_try_string (key));
140 141
}

Havoc Pennington's avatar
Havoc Pennington committed
142 143 144
/**
 * gdk_drawable_get_size:
 * @drawable: a #GdkDrawable
Johan Dahlin's avatar
Johan Dahlin committed
145 146
 * @width: (allow-none): (out): location to store drawable's width, or %NULL
 * @height: (allow-none): (out): location to store drawable's height, or %NULL
Havoc Pennington's avatar
Havoc Pennington committed
147 148 149
 *
 * Fills *@width and *@height with the size of @drawable.
 * @width or @height can be %NULL if you only want the other one.
150
 *
Havoc Pennington's avatar
Havoc Pennington committed
151 152 153 154
 * On the X11 platform, if @drawable is a #GdkWindow, the returned
 * size is the size reported in the most-recently-processed configure
 * event, rather than the current size on the X server.
 * 
Havoc Pennington's avatar
Havoc Pennington committed
155
 **/
156 157 158 159 160
void
gdk_drawable_get_size (GdkDrawable *drawable,
		       gint        *width,
		       gint        *height)
{
161 162
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));

Cody Russell's avatar
Updates  
Cody Russell committed
163 164
  if (GDK_DRAWABLE_GET_CLASS (drawable)->get_size != NULL)
    GDK_DRAWABLE_GET_CLASS (drawable)->get_size (drawable, width, height);  
165 166
}

Havoc Pennington's avatar
Havoc Pennington committed
167 168 169 170 171 172 173 174
/**
 * gdk_drawable_get_visual:
 * @drawable: a #GdkDrawable
 * 
 * Gets the #GdkVisual describing the pixel format of @drawable.
 * 
 * Return value: a #GdkVisual
 **/
175 176 177
GdkVisual*
gdk_drawable_get_visual (GdkDrawable *drawable)
{
178 179 180
  g_return_val_if_fail (GDK_IS_DRAWABLE (drawable), NULL);
  
  return GDK_DRAWABLE_GET_CLASS (drawable)->get_visual (drawable);
181 182
}

Havoc Pennington's avatar
Havoc Pennington committed
183 184 185 186 187 188 189 190 191 192
/**
 * gdk_drawable_get_depth:
 * @drawable: a #GdkDrawable
 * 
 * Obtains the bit depth of the drawable, that is, the number of bits
 * that make up a pixel in the drawable's visual. Examples are 8 bits
 * per pixel, 24 bits per pixel, etc.
 * 
 * Return value: number of bits per pixel
 **/
193 194 195
gint
gdk_drawable_get_depth (GdkDrawable *drawable)
{
196
  g_return_val_if_fail (GDK_IS_DRAWABLE (drawable), 0);
197

198 199
  return GDK_DRAWABLE_GET_CLASS (drawable)->get_depth (drawable);
}
200 201 202 203 204 205 206
/**
 * gdk_drawable_get_screen:
 * @drawable: a #GdkDrawable
 * 
 * Gets the #GdkScreen associated with a #GdkDrawable.
 * 
 * Return value: the #GdkScreen associated with @drawable
Matthias Clasen's avatar
Matthias Clasen committed
207 208
 *
 * Since: 2.2
209 210 211 212 213 214 215 216
 **/
GdkScreen*
gdk_drawable_get_screen(GdkDrawable *drawable)
{
  g_return_val_if_fail (GDK_IS_DRAWABLE (drawable), NULL);

  return GDK_DRAWABLE_GET_CLASS (drawable)->get_screen (drawable);
}
217

218 219 220 221 222 223 224
/**
 * gdk_drawable_get_display:
 * @drawable: a #GdkDrawable
 * 
 * Gets the #GdkDisplay associated with a #GdkDrawable.
 * 
 * Return value: the #GdkDisplay associated with @drawable
Matthias Clasen's avatar
Matthias Clasen committed
225 226
 *
 * Since: 2.2
227 228 229 230 231 232 233 234 235
 **/
GdkDisplay*
gdk_drawable_get_display (GdkDrawable *drawable)
{
  g_return_val_if_fail (GDK_IS_DRAWABLE (drawable), NULL);
  
  return gdk_screen_get_display (gdk_drawable_get_screen (drawable));
}
	
Havoc Pennington's avatar
Havoc Pennington committed
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
/**
 * gdk_drawable_set_colormap:
 * @drawable: a #GdkDrawable
 * @colormap: a #GdkColormap
 *
 * Sets the colormap associated with @drawable. Normally this will
 * happen automatically when the drawable is created; you only need to
 * use this function if the drawable-creating function did not have a
 * way to determine the colormap, and you then use drawable operations
 * that require a colormap. The colormap for all drawables and
 * graphics contexts you intend to use together should match. i.e.
 * when using a #GdkGC to draw to a drawable, or copying one drawable
 * to another, the colormaps should match.
 * 
 **/
251 252 253 254 255
void
gdk_drawable_set_colormap (GdkDrawable *drawable,
                           GdkColormap *cmap)
{
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
256 257
  g_return_if_fail (cmap == NULL || gdk_drawable_get_depth (drawable)
                    == cmap->visual->depth);
258 259 260 261

  GDK_DRAWABLE_GET_CLASS (drawable)->set_colormap (drawable, cmap);
}

Havoc Pennington's avatar
Havoc Pennington committed
262 263 264 265 266 267 268 269 270
/**
 * gdk_drawable_get_colormap:
 * @drawable: a #GdkDrawable
 * 
 * Gets the colormap for @drawable, if one is set; returns
 * %NULL otherwise.
 * 
 * Return value: the colormap, or %NULL
 **/
271 272 273 274 275 276
GdkColormap*
gdk_drawable_get_colormap (GdkDrawable *drawable)
{
  g_return_val_if_fail (GDK_IS_DRAWABLE (drawable), NULL);

  return GDK_DRAWABLE_GET_CLASS (drawable)->get_colormap (drawable);
277 278
}

Havoc Pennington's avatar
Havoc Pennington committed
279 280 281 282 283 284 285 286
/**
 * gdk_drawable_ref:
 * @drawable: a #GdkDrawable
 * 
 * Deprecated equivalent of calling g_object_ref() on @drawable.
 * (Drawables were not objects in previous versions of GDK.)
 * 
 * Return value: the same @drawable passed in
287 288
 *
 * Deprecated: 2.0: Use g_object_ref() instead.
Havoc Pennington's avatar
Havoc Pennington committed
289
 **/
290 291 292
GdkDrawable*
gdk_drawable_ref (GdkDrawable *drawable)
{
293
  return (GdkDrawable *) g_object_ref (drawable);
294 295
}

Havoc Pennington's avatar
Havoc Pennington committed
296 297 298
/**
 * gdk_drawable_unref:
 * @drawable: a #GdkDrawable
299
 *
Havoc Pennington's avatar
Havoc Pennington committed
300 301
 * Deprecated equivalent of calling g_object_unref() on @drawable.
 * 
302
 * Deprecated: 2.0: Use g_object_unref() instead.
Havoc Pennington's avatar
Havoc Pennington committed
303
 **/
304 305 306
void
gdk_drawable_unref (GdkDrawable *drawable)
{
307 308
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));

309
  g_object_unref (drawable);
310 311
}

312 313
/* Drawing
 */
314 315 316 317 318 319 320 321 322 323 324

/**
 * gdk_draw_point:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @gc: a #GdkGC.
 * @x: the x coordinate of the point.
 * @y: the y coordinate of the point.
 * 
 * Draws a point, using the foreground color and other attributes of 
 * the #GdkGC.
 **/
Elliot Lee's avatar
Elliot Lee committed
325 326 327 328 329 330
void
gdk_draw_point (GdkDrawable *drawable,
                GdkGC       *gc,
                gint         x,
                gint         y)
{
331
  GdkPoint point;
Elliot Lee's avatar
Elliot Lee committed
332

333 334
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  g_return_if_fail (GDK_IS_GC (gc));
Elliot Lee's avatar
Elliot Lee committed
335

336 337 338
  point.x = x;
  point.y = y;
  
339
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_points (drawable, gc, &point, 1);
Elliot Lee's avatar
Elliot Lee committed
340 341
}

342 343 344 345
/**
 * gdk_draw_line:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap). 
 * @gc: a #GdkGC.
346 347 348 349
 * @x1_: the x coordinate of the start point.
 * @y1_: the y coordinate of the start point.
 * @x2_: the x coordinate of the end point.
 * @y2_: the y coordinate of the end point.
350 351 352 353
 * 
 * Draws a line, using the foreground color and other attributes of 
 * the #GdkGC.
 **/
Elliot Lee's avatar
Elliot Lee committed
354 355 356 357 358 359 360 361
void
gdk_draw_line (GdkDrawable *drawable,
	       GdkGC       *gc,
	       gint         x1,
	       gint         y1,
	       gint         x2,
	       gint         y2)
{
362
  GdkSegment segment;
Elliot Lee's avatar
Elliot Lee committed
363

364 365
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  g_return_if_fail (GDK_IS_GC (gc));
Elliot Lee's avatar
Elliot Lee committed
366

367 368 369 370
  segment.x1 = x1;
  segment.y1 = y1;
  segment.x2 = x2;
  segment.y2 = y2;
371
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_segments (drawable, gc, &segment, 1);
Elliot Lee's avatar
Elliot Lee committed
372 373
}

374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394
/**
 * gdk_draw_rectangle:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @gc: a #GdkGC.
 * @filled: %TRUE if the rectangle should be filled.
 * @x: the x coordinate of the left edge of the rectangle.
 * @y: the y coordinate of the top edge of the rectangle.
 * @width: the width of the rectangle.
 * @height: the height of the rectangle.
 * 
 * Draws a rectangular outline or filled rectangle, using the foreground color
 * and other attributes of the #GdkGC.
 *
 * A rectangle drawn filled is 1 pixel smaller in both dimensions than a 
 * rectangle outlined. Calling 
 * <literal>gdk_draw_rectangle (window, gc, TRUE, 0, 0, 20, 20)</literal> 
 * results in a filled rectangle 20 pixels wide and 20 pixels high. Calling
 * <literal>gdk_draw_rectangle (window, gc, FALSE, 0, 0, 20, 20)</literal> 
 * results in an outlined rectangle with corners at (0, 0), (0, 20), (20, 20),
 * and (20, 0), which makes it 21 pixels wide and 21 pixels high.
 **/
Elliot Lee's avatar
Elliot Lee committed
395 396 397
void
gdk_draw_rectangle (GdkDrawable *drawable,
		    GdkGC       *gc,
398
		    gboolean     filled,
Elliot Lee's avatar
Elliot Lee committed
399 400 401 402
		    gint         x,
		    gint         y,
		    gint         width,
		    gint         height)
403 404 405
{  
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  g_return_if_fail (GDK_IS_GC (gc));
Elliot Lee's avatar
Elliot Lee committed
406

407 408 409 410 411 412 413 414 415 416 417 418
  if (width < 0 || height < 0)
    {
      gint real_width;
      gint real_height;
      
      gdk_drawable_get_size (drawable, &real_width, &real_height);

      if (width < 0)
        width = real_width;
      if (height < 0)
        height = real_height;
    }
Elliot Lee's avatar
Elliot Lee committed
419

420 421
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_rectangle (drawable, gc, filled, x, y,
                                                     width, height);
Elliot Lee's avatar
Elliot Lee committed
422 423
}

424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441
/**
 * gdk_draw_arc:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @gc: a #GdkGC.
 * @filled: %TRUE if the arc should be filled, producing a 'pie slice'.
 * @x: the x coordinate of the left edge of the bounding rectangle.
 * @y: the y coordinate of the top edge of the bounding rectangle.
 * @width: the width of the bounding rectangle.
 * @height: the height of the bounding rectangle.
 * @angle1: the start angle of the arc, relative to the 3 o'clock position,
 *     counter-clockwise, in 1/64ths of a degree.
 * @angle2: the end angle of the arc, relative to @angle1, in 1/64ths 
 *     of a degree.
 * 
 * Draws an arc or a filled 'pie slice'. The arc is defined by the bounding
 * rectangle of the entire ellipse, and the start and end angles of the part 
 * of the ellipse to be drawn.
 **/
Elliot Lee's avatar
Elliot Lee committed
442 443 444
void
gdk_draw_arc (GdkDrawable *drawable,
	      GdkGC       *gc,
445
	      gboolean     filled,
Elliot Lee's avatar
Elliot Lee committed
446 447 448 449 450 451
	      gint         x,
	      gint         y,
	      gint         width,
	      gint         height,
	      gint         angle1,
	      gint         angle2)
452 453 454
{  
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  g_return_if_fail (GDK_IS_GC (gc));
Elliot Lee's avatar
Elliot Lee committed
455

456 457 458 459 460 461 462 463 464 465 466 467
  if (width < 0 || height < 0)
    {
      gint real_width;
      gint real_height;
      
      gdk_drawable_get_size (drawable, &real_width, &real_height);

      if (width < 0)
        width = real_width;
      if (height < 0)
        height = real_height;
    }
Elliot Lee's avatar
Elliot Lee committed
468

469 470
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_arc (drawable, gc, filled,
                                               x, y, width, height, angle1, angle2);
Elliot Lee's avatar
Elliot Lee committed
471 472
}

473 474 475 476 477 478 479 480 481
/**
 * gdk_draw_polygon:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @gc: a #GdkGC.
 * @filled: %TRUE if the polygon should be filled. The polygon is closed
 *     automatically, connecting the last point to the first point if 
 *     necessary.
 * @points: an array of #GdkPoint structures specifying the points making 
 *     up the polygon.
482
 * @n_points: the number of points.
483 484 485
 * 
 * Draws an outlined or filled polygon.
 **/
Elliot Lee's avatar
Elliot Lee committed
486
void
487 488 489 490 491
gdk_draw_polygon (GdkDrawable    *drawable,
		  GdkGC          *gc,
		  gboolean        filled,
		  const GdkPoint *points,
		  gint            n_points)
Elliot Lee's avatar
Elliot Lee committed
492
{
493 494
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  g_return_if_fail (GDK_IS_GC (gc));
Elliot Lee's avatar
Elliot Lee committed
495

496
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_polygon (drawable, gc, filled,
497 498
                                                   (GdkPoint *) points,
                                                   n_points);
Elliot Lee's avatar
Elliot Lee committed
499 500 501 502 503 504 505 506
}

/* gdk_draw_string
 *
 * Modified by Li-Da Lho to draw 16 bits and Multibyte strings
 *
 * Interface changed: add "GdkFont *font" to specify font or fontset explicitely
 */
507 508 509 510 511 512 513 514 515 516
/**
 * gdk_draw_string:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @font: a #GdkFont.
 * @gc: a #GdkGC.
 * @x: the x coordinate of the left edge of the text.
 * @y: the y coordinate of the baseline of the text.
 * @string:  the string of characters to draw.
 * 
 * Draws a string of characters in the given font or fontset.
517
 * 
518
 * Deprecated: 2.4: Use gdk_draw_layout() instead.
519
 **/
Elliot Lee's avatar
Elliot Lee committed
520 521 522 523 524 525 526 527
void
gdk_draw_string (GdkDrawable *drawable,
		 GdkFont     *font,
		 GdkGC       *gc,
		 gint         x,
		 gint         y,
		 const gchar *string)
{
528
  gdk_draw_text (drawable, font, gc, x, y, string, _gdk_font_strlen (font, string));
Elliot Lee's avatar
Elliot Lee committed
529 530 531 532 533 534 535 536
}

/* gdk_draw_text
 *
 * Modified by Li-Da Lho to draw 16 bits and Multibyte strings
 *
 * Interface changed: add "GdkFont *font" to specify font or fontset explicitely
 */
537 538 539 540 541 542 543 544 545 546 547
/**
 * gdk_draw_text:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @font: a #GdkFont.
 * @gc: a #GdkGC.
 * @x: the x coordinate of the left edge of the text.
 * @y: the y coordinate of the baseline of the text.
 * @text:  the characters to draw.
 * @text_length: the number of characters of @text to draw.
 * 
 * Draws a number of characters in the given font or fontset.
548
 *
549
 * Deprecated: 2.4: Use gdk_draw_layout() instead.
550
 **/
Elliot Lee's avatar
Elliot Lee committed
551 552 553 554 555 556 557 558 559
void
gdk_draw_text (GdkDrawable *drawable,
	       GdkFont     *font,
	       GdkGC       *gc,
	       gint         x,
	       gint         y,
	       const gchar *text,
	       gint         text_length)
{
560
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
Elliot Lee's avatar
Elliot Lee committed
561
  g_return_if_fail (font != NULL);
562
  g_return_if_fail (GDK_IS_GC (gc));
Elliot Lee's avatar
Elliot Lee committed
563 564
  g_return_if_fail (text != NULL);

565
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_text (drawable, font, gc, x, y, text, text_length);
Elliot Lee's avatar
Elliot Lee committed
566 567
}

568 569 570 571 572 573 574 575 576 577 578 579 580
/**
 * gdk_draw_text_wc:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @font: a #GdkFont.
 * @gc: a #GdkGC.
 * @x: the x coordinate of the left edge of the text.
 * @y: the y coordinate of the baseline of the text.
 * @text: the wide characters to draw.
 * @text_length: the number of characters to draw.
 * 
 * Draws a number of wide characters using the given font of fontset.
 * If the font is a 1-byte font, the string is converted into 1-byte 
 * characters (discarding the high bytes) before output.
581
 * 
582
 * Deprecated: 2.4: Use gdk_draw_layout() instead.
583
 **/
584 585 586 587 588 589 590 591 592
void
gdk_draw_text_wc (GdkDrawable	 *drawable,
		  GdkFont	 *font,
		  GdkGC		 *gc,
		  gint		  x,
		  gint		  y,
		  const GdkWChar *text,
		  gint		  text_length)
{
593
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
594
  g_return_if_fail (font != NULL);
595
  g_return_if_fail (GDK_IS_GC (gc));
596 597
  g_return_if_fail (text != NULL);

598
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_text_wc (drawable, font, gc, x, y, text, text_length);
599 600
}

Havoc Pennington's avatar
Havoc Pennington committed
601 602 603 604
/**
 * gdk_draw_drawable:
 * @drawable: a #GdkDrawable
 * @gc: a #GdkGC sharing the drawable's visual and colormap
Matthias Clasen's avatar
Matthias Clasen committed
605
 * @src: the source #GdkDrawable, which may be the same as @drawable
Havoc Pennington's avatar
Havoc Pennington committed
606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624
 * @xsrc: X position in @src of rectangle to draw
 * @ysrc: Y position in @src of rectangle to draw
 * @xdest: X position in @drawable where the rectangle should be drawn
 * @ydest: Y position in @drawable where the rectangle should be drawn
 * @width: width of rectangle to draw, or -1 for entire @src width
 * @height: height of rectangle to draw, or -1 for entire @src height
 *
 * Copies the @width x @height region of @src at coordinates (@xsrc,
 * @ysrc) to coordinates (@xdest, @ydest) in @drawable.
 * @width and/or @height may be given as -1, in which case the entire
 * @src drawable will be copied.
 *
 * Most fields in @gc are not used for this operation, but notably the
 * clip mask or clip region will be honored.
 *
 * The source and destination drawables must have the same visual and
 * colormap, or errors will result. (On X11, failure to match
 * visual/colormap results in a BadMatch error from the X server.)
 * A common cause of this problem is an attempt to draw a bitmap to
Matthias Clasen's avatar
2.7.3  
Matthias Clasen committed
625 626 627
 * a color drawable. The way to draw a bitmap is to set the bitmap as 
 * the stipple on the #GdkGC, set the fill mode to %GDK_STIPPLED, and 
 * then draw the rectangle.
Havoc Pennington's avatar
Havoc Pennington committed
628
 **/
Elliot Lee's avatar
Elliot Lee committed
629
void
630 631 632 633 634 635 636 637 638
gdk_draw_drawable (GdkDrawable *drawable,
		   GdkGC       *gc,
		   GdkDrawable *src,
		   gint         xsrc,
		   gint         ysrc,
		   gint         xdest,
		   gint         ydest,
		   gint         width,
		   gint         height)
Elliot Lee's avatar
Elliot Lee committed
639
{
640
  GdkDrawable *composite;
Havoc Pennington's avatar
Havoc Pennington committed
641 642 643
  gint composite_x_offset = 0;
  gint composite_y_offset = 0;

644
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
645
  g_return_if_fail (GDK_IS_DRAWABLE (src));
646
  g_return_if_fail (GDK_IS_GC (gc));
Elliot Lee's avatar
Elliot Lee committed
647

648 649 650 651 652 653 654 655 656 657 658 659
  if (width < 0 || height < 0)
    {
      gint real_width;
      gint real_height;
      
      gdk_drawable_get_size (src, &real_width, &real_height);

      if (width < 0)
        width = real_width;
      if (height < 0)
        height = real_height;
    }
Elliot Lee's avatar
Elliot Lee committed
660

Havoc Pennington's avatar
Havoc Pennington committed
661 662 663 664 665 666 667 668

  composite =
    GDK_DRAWABLE_GET_CLASS (src)->get_composite_drawable (src,
                                                          xsrc, ysrc,
                                                          width, height,
                                                          &composite_x_offset,
                                                          &composite_y_offset);

669
  /* TODO: For non-native windows this may copy stuff from other overlapping
670 671 672
     windows. We should clip that and (for windows with bg != None) clear that
     area in the destination instead. */

673 674
  if (GDK_DRAWABLE_GET_CLASS (drawable)->draw_drawable_with_src)
    GDK_DRAWABLE_GET_CLASS (drawable)->draw_drawable_with_src (drawable, gc,
675
							       composite,
676 677 678 679 680 681 682
							       xsrc - composite_x_offset,
							       ysrc - composite_y_offset,
							       xdest, ydest,
							       width, height,
							       src);
  else /* backwards compat for old out-of-tree implementations of GdkDrawable (are there any?) */
    GDK_DRAWABLE_GET_CLASS (drawable)->draw_drawable (drawable, gc,
683
						      composite,
684 685 686 687
						      xsrc - composite_x_offset,
						      ysrc - composite_y_offset,
						      xdest, ydest,
						      width, height);
688

689
  g_object_unref (composite);
Elliot Lee's avatar
Elliot Lee committed
690 691
}

692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708
/**
 * gdk_draw_image:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @gc: a #GdkGC.
 * @image: the #GdkImage to draw.
 * @xsrc: the left edge of the source rectangle within @image.
 * @ysrc: the top of the source rectangle within @image.
 * @xdest: the x coordinate of the destination within @drawable.
 * @ydest: the y coordinate of the destination within @drawable.
 * @width: the width of the area to be copied, or -1 to make the area 
 *     extend to the right edge of @image.
 * @height: the height of the area to be copied, or -1 to make the area 
 *     extend to the bottom edge of @image.
 * 
 * Draws a #GdkImage onto a drawable.
 * The depth of the #GdkImage must match the depth of the #GdkDrawable.
 **/
Elliot Lee's avatar
Elliot Lee committed
709 710 711 712 713 714 715 716 717 718 719
void
gdk_draw_image (GdkDrawable *drawable,
		GdkGC       *gc,
		GdkImage    *image,
		gint         xsrc,
		gint         ysrc,
		gint         xdest,
		gint         ydest,
		gint         width,
		gint         height)
{
720
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
721
  g_return_if_fail (GDK_IS_IMAGE (image));
722
  g_return_if_fail (GDK_IS_GC (gc));
Elliot Lee's avatar
Elliot Lee committed
723 724 725 726 727 728

  if (width == -1)
    width = image->width;
  if (height == -1)
    height = image->height;

729 730
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_image (drawable, gc, image, xsrc, ysrc,
                                                 xdest, ydest, width, height);
Elliot Lee's avatar
Elliot Lee committed
731 732
}

733
/**
734
 * gdk_draw_pixbuf:
735
 * @drawable: Destination drawable.
Johan Dahlin's avatar
Johan Dahlin committed
736
 * @gc: (allow-none): a #GdkGC, used for clipping, or %NULL
737 738 739 740 741 742 743
 * @pixbuf: a #GdkPixbuf
 * @src_x: Source X coordinate within pixbuf.
 * @src_y: Source Y coordinates within pixbuf.
 * @dest_x: Destination X coordinate within drawable.
 * @dest_y: Destination Y coordinate within drawable.
 * @width: Width of region to render, in pixels, or -1 to use pixbuf width.
 * @height: Height of region to render, in pixels, or -1 to use pixbuf height.
Matthias Clasen's avatar
Matthias Clasen committed
744
 * @dither: Dithering mode for #GdkRGB.
745 746 747 748 749
 * @x_dither: X offset for dither.
 * @y_dither: Y offset for dither.
 * 
 * Renders a rectangular portion of a pixbuf to a drawable.  The destination
 * drawable must have a colormap. All windows have a colormap, however, pixmaps
Matthias Clasen's avatar
Matthias Clasen committed
750 751 752 753 754 755
 * only have colormap by default if they were created with a non-%NULL window 
 * argument. Otherwise a colormap must be set on them with 
 * gdk_drawable_set_colormap().
 *
 * On older X servers, rendering pixbufs with an alpha channel involves round 
 * trips to the X server, and may be somewhat slow.
756
 *
757 758 759 760 761 762
 * If GDK is built with the Sun mediaLib library, the gdk_draw_pixbuf
 * function is 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.
 *
Matthias Clasen's avatar
Matthias Clasen committed
763
 * Since: 2.2
764 765
 **/
void
766
gdk_draw_pixbuf (GdkDrawable     *drawable,
767 768 769 770 771 772 773 774 775 776 777
                 GdkGC           *gc,
                 const GdkPixbuf *pixbuf,
                 gint             src_x,
                 gint             src_y,
                 gint             dest_x,
                 gint             dest_y,
                 gint             width,
                 gint             height,
                 GdkRgbDither     dither,
                 gint             x_dither,
                 gint             y_dither)
778 779 780 781 782
{
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  g_return_if_fail (gc == NULL || GDK_IS_GC (gc));
  g_return_if_fail (GDK_IS_PIXBUF (pixbuf));

783 784 785
  if (width == 0 || height == 0)
    return;

786 787 788 789 790
  if (width == -1)
    width = gdk_pixbuf_get_width (pixbuf);
  if (height == -1)
    height = gdk_pixbuf_get_height (pixbuf);

791 792
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_pixbuf (drawable, gc,
                                                  (GdkPixbuf *) pixbuf,
793 794
						  src_x, src_y, dest_x, dest_y,
                                                  width, height,
795
						  dither, x_dither, y_dither);
796 797
}

798 799 800 801 802
/**
 * gdk_draw_points:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @gc: a #GdkGC.
 * @points: an array of #GdkPoint structures.
803
 * @n_points: the number of points to be drawn.
804 805 806 807
 * 
 * Draws a number of points, using the foreground color and other 
 * attributes of the #GdkGC.
 **/
Elliot Lee's avatar
Elliot Lee committed
808
void
809 810 811 812
gdk_draw_points (GdkDrawable    *drawable,
		 GdkGC          *gc,
		 const GdkPoint *points,
		 gint            n_points)
Elliot Lee's avatar
Elliot Lee committed
813
{
814
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
815
  g_return_if_fail ((points != NULL) && (n_points > 0));
816
  g_return_if_fail (GDK_IS_GC (gc));
817
  g_return_if_fail (n_points >= 0);
818

819
  if (n_points == 0)
820
    return;
Elliot Lee's avatar
Elliot Lee committed
821

822 823
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_points (drawable, gc,
                                                  (GdkPoint *) points, n_points);
Elliot Lee's avatar
Elliot Lee committed
824 825
}

826 827 828 829 830 831
/**
 * gdk_draw_segments:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @gc: a #GdkGC.
 * @segs: an array of #GdkSegment structures specifying the start and 
 *   end points of the lines to be drawn.
832
 * @n_segs: the number of line segments to draw, i.e. the size of the 
833 834 835 836
 *   @segs array.
 * 
 * Draws a number of unconnected lines.
 **/
Elliot Lee's avatar
Elliot Lee committed
837
void
838 839 840 841
gdk_draw_segments (GdkDrawable      *drawable,
		   GdkGC            *gc,
		   const GdkSegment *segs,
		   gint              n_segs)
Elliot Lee's avatar
Elliot Lee committed
842
{
843
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
844

845
  if (n_segs == 0)
846
    return;
Elliot Lee's avatar
Elliot Lee committed
847

848
  g_return_if_fail (segs != NULL);
849
  g_return_if_fail (GDK_IS_GC (gc));
850
  g_return_if_fail (n_segs >= 0);
851

852 853
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_segments (drawable, gc,
                                                    (GdkSegment *) segs, n_segs);
Elliot Lee's avatar
Elliot Lee committed
854
}
855

856 857 858 859 860
/**
 * gdk_draw_lines:
 * @drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 * @gc: a #GdkGC.
 * @points: an array of #GdkPoint structures specifying the endpoints of the
861
 * @n_points: the size of the @points array.
862 863 864 865 866 867
 * 
 * Draws a series of lines connecting the given points.
 * The way in which joins between lines are draw is determined by the
 * #GdkCapStyle value in the #GdkGC. This can be set with
 * gdk_gc_set_line_attributes().
 **/
868
void
869 870 871 872
gdk_draw_lines (GdkDrawable    *drawable,
		GdkGC          *gc,
		const GdkPoint *points,
		gint            n_points)
873
{
874
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
875
  g_return_if_fail (points != NULL);
876
  g_return_if_fail (GDK_IS_GC (gc));
877
  g_return_if_fail (n_points >= 0);
878

879
  if (n_points == 0)
880
    return;
881

882 883
  GDK_DRAWABLE_GET_CLASS (drawable)->draw_lines (drawable, gc,
                                                 (GdkPoint *) points, n_points);
884
}
885

886
static void
887 888 889 890 891 892 893
real_draw_glyphs (GdkDrawable       *drawable,
		  GdkGC	            *gc,
		  const PangoMatrix *matrix,
		  PangoFont         *font,
		  gdouble            x,
		  gdouble            y,
		  PangoGlyphString  *glyphs)
894 895 896
{
  cairo_t *cr;

897
  cr = gdk_cairo_create (drawable);
898
  _gdk_gc_update_context (gc, cr, NULL, NULL, TRUE, drawable);
899 900 901

  if (matrix)
    {
902 903 904 905 906 907 908 909
      cairo_matrix_t cairo_matrix;

      cairo_matrix.xx = matrix->xx;
      cairo_matrix.yx = matrix->yx;
      cairo_matrix.xy = matrix->xy;
      cairo_matrix.yy = matrix->yy;
      cairo_matrix.x0 = matrix->x0;
      cairo_matrix.y0 = matrix->y0;
910
      
911
      cairo_set_matrix (cr, &cairo_matrix);
912 913 914 915 916 917 918 919
    }

  cairo_move_to (cr, x, y);
  pango_cairo_show_glyph_string (cr, font, glyphs);

  cairo_destroy (cr);
}

Havoc Pennington's avatar
Havoc Pennington committed
920 921 922 923 924 925 926
/**
 * gdk_draw_glyphs:
 * @drawable: a #GdkDrawable
 * @gc: a #GdkGC
 * @font: font to be used
 * @x: X coordinate of baseline origin
 * @y: Y coordinate of baseline origin
927
 * @glyphs: the glyph string to draw
Havoc Pennington's avatar
Havoc Pennington committed
928 929 930 931
 *
 * This is a low-level function; 99% of text rendering should be done
 * using gdk_draw_layout() instead.
 *
932
 * A glyph is a single image in a font. This function draws a sequence of
Havoc Pennington's avatar
Havoc Pennington committed
933 934 935 936 937 938
 * glyphs.  To obtain a sequence of glyphs you have to understand a
 * lot about internationalized text handling, which you don't want to
 * understand; thus, use gdk_draw_layout() instead of this function,
 * gdk_draw_layout() handles the details.
 * 
 **/
939 940 941 942 943 944 945 946
void
gdk_draw_glyphs (GdkDrawable      *drawable,
		 GdkGC            *gc,
		 PangoFont        *font,
		 gint              x,
		 gint              y,
		 PangoGlyphString *glyphs)
{
947 948
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  g_return_if_fail (GDK_IS_GC (gc));
949 950 951
  
  real_draw_glyphs (drawable, gc, NULL, font,
		    x, y, glyphs);
952
}
953

954 955 956 957
/**
 * gdk_draw_glyphs_transformed:
 * @drawable: a #GdkDrawable
 * @gc: a #GdkGC
Johan Dahlin's avatar
Johan Dahlin committed
958
 * @matrix: (allow-none): a #PangoMatrix, or %NULL to use an identity transformation
959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977
 * @font: the font in which to draw the string
 * @x:       the x position of the start of the string (in Pango
 *           units in user space coordinates)
 * @y:       the y position of the baseline (in Pango units
 *           in user space coordinates)
 * @glyphs:  the glyph string to draw
 * 
 * Renders a #PangoGlyphString onto a drawable, possibly
 * transforming the layed-out coordinates through a transformation
 * matrix. Note that the transformation matrix for @font is not
 * changed, so to produce correct rendering results, the @font
 * must have been loaded using a #PangoContext with an identical
 * transformation matrix to that passed in to this function.
 *
 * See also gdk_draw_glyphs(), gdk_draw_layout().
 *
 * Since: 2.6
 **/
void
978 979 980 981 982 983 984
gdk_draw_glyphs_transformed (GdkDrawable       *drawable,
			     GdkGC	       *gc,
			     const PangoMatrix *matrix,
			     PangoFont         *font,
			     gint               x,
			     gint               y,
			     PangoGlyphString  *glyphs)
985 986 987 988
{
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  g_return_if_fail (GDK_IS_GC (gc));

989 990
  real_draw_glyphs (drawable, gc, matrix, font,
		    x / PANGO_SCALE, y / PANGO_SCALE, glyphs);
991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008
}

/**
 * gdk_draw_trapezoids:
 * @drawable: a #GdkDrawable
 * @gc: a #GdkGC
 * @trapezoids: an array of #GdkTrapezoid structures
 * @n_trapezoids: the number of trapezoids to draw
 * 
 * Draws a set of anti-aliased trapezoids. The trapezoids are
 * combined using saturation addition, then drawn over the background
 * as a set. This is low level functionality used internally to implement
 * rotated underlines and backgrouds when rendering a PangoLayout and is
 * likely not useful for applications.
 *
 * Since: 2.6
 **/
void
1009 1010 1011 1012
gdk_draw_trapezoids (GdkDrawable        *drawable,
		     GdkGC	        *gc,
		     const GdkTrapezoid *trapezoids,
		     gint                n_trapezoids)
1013
{
1014 1015 1016
  cairo_t *cr;
  int i;

1017 1018 1019 1020
  g_return_if_fail (GDK_IS_DRAWABLE (drawable));
  g_return_if_fail (GDK_IS_GC (gc));
  g_return_if_fail (n_trapezoids == 0 || trapezoids != NULL);

1021
  cr = gdk_cairo_create (drawable);
1022
  _gdk_gc_update_context (gc, cr, NULL, NULL, TRUE, drawable);
1023 1024 1025 1026 1027 1028
  
  for (i = 0; i < n_trapezoids; i++)
    {
      cairo_move_to (cr, trapezoids[i].x11, trapezoids[i].y1);
      cairo_line_to (cr, trapezoids[i].x21, trapezoids[i].y1);
      cairo_line_to (cr, trapezoids[i].x22, trapezoids[i].y2);
1029
      cairo_line_to (cr, trapezoids[i].x12, trapezoids[i].y2);
1030 1031 1032 1033 1034 1035
      cairo_close_path (cr);
    }

  cairo_fill (cr);

  cairo_destroy (cr);
1036
}
1037

1038
/**
1039
 * gdk_drawable_copy_to_image:
1040
 * @drawable: a #GdkDrawable
Johan Dahlin's avatar
Johan Dahlin committed
1041
 * @image: (allow-none): a #GdkDrawable, or %NULL if a new @image should be created.
1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053
 * @src_x: x coordinate on @drawable
 * @src_y: y coordinate on @drawable
 * @dest_x: x coordinate within @image. Must be 0 if @image is %NULL
 * @dest_y: y coordinate within @image. Must be 0 if @image is %NULL
 * @width: width of region to get
 * @height: height or region to get
 *
 * Copies a portion of @drawable into the client side image structure
 * @image. If @image is %NULL, creates a new image of size @width x @height
 * and copies into that. See gdk_drawable_get_image() for further details.
 * 
 * Return value: @image, or a new a #GdkImage containing the contents
1054 1055 1056
 *               of @drawable
 * 
 * Since: 2.4
1057 1058
 **/
GdkImage*
1059 1060 1061 1062 1063 1064 1065 1066
gdk_drawable_copy_to_image (GdkDrawable *drawable,
			    GdkImage    *image,
			    gint         src_x,
			    gint         src_y,
			    gint         dest_x,
			    gint         dest_y,
			    gint         width,
			    gint         height)
1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100
{
  GdkDrawable *composite;
  gint composite_x_offset = 0;
  gint composite_y_offset = 0;
  GdkImage *retval;
  GdkColormap *cmap;
  
  g_return_val_if_fail (GDK_IS_DRAWABLE (drawable), NULL);
  g_return_val_if_fail (src_x >= 0, NULL);
  g_return_val_if_fail (src_y >= 0, NULL);

  /* FIXME? Note race condition since we get the size then
   * get the image, and the size may have changed.
   */
  
  if (width < 0 || height < 0)
    gdk_drawable_get_size (drawable,
                           width < 0 ? &width : NULL,
                           height < 0 ? &height : NULL);
  
  composite =
    GDK_DRAWABLE_GET_CLASS (drawable)->get_composite_drawable (drawable,
                                                               src_x, src_y,
                                                               width, height,
                                                               &composite_x_offset,
                                                               &composite_y_offset); 
  
  retval = GDK_DRAWABLE_GET_CLASS (composite)->_copy_to_image (composite,
							       image,
							       src_x - composite_x_offset,
							       src_y - composite_y_offset,
							       dest_x, dest_y,
							       width, height);

1101
  g_object_unref (composite);
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113

  if (!image && retval)
    {
      cmap = gdk_drawable_get_colormap (drawable);
      
      if (cmap)
	gdk_image_set_colormap (retval, cmap);
    }
  
  return retval;
}

Havoc Pennington's avatar
Havoc Pennington committed
1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146
/**
 * gdk_drawable_get_image:
 * @drawable: a #GdkDrawable
 * @x: x coordinate on @drawable
 * @y: y coordinate on @drawable
 * @width: width of region to get
 * @height: height or region to get
 * 
 * A #GdkImage stores client-side image data (pixels). In contrast,
 * #GdkPixmap and #GdkWindow are server-side
 * objects. gdk_drawable_get_image() obtains the pixels from a
 * server-side drawable as a client-side #GdkImage.  The format of a
 * #GdkImage depends on the #GdkVisual of the current display, which
 * makes manipulating #GdkImage extremely difficult; therefore, in
 * most cases you should use gdk_pixbuf_get_from_drawable() instead of
 * this lower-level function. A #GdkPixbuf contains image data in a
 * canonicalized RGB format, rather than a display-dependent format.
 * Of course, there's a convenience vs. speed tradeoff here, so you'll
 * want to think about what makes sense for your application.
 *
 * @x, @y, @width, and @height define the region of @drawable to
 * obtain as an image.
 *
 * You would usually copy image data to the client side if you intend
 * to examine the values of individual pixels, for example to darken
 * an image or add a red tint. It would be prohibitively slow to
 * make a round-trip request to the windowing system for each pixel,
 * so instead you get all of them at once, modify them, then copy
 * them all back at once.
 *
 * If the X server or other windowing system backend is on the local
 * machine, this function may use shared memory to avoid copying
 * the image data.
1147 1148 1149 1150
 *
 * If the source drawable is a #GdkWindow and partially offscreen
 * or obscured, then the obscured portions of the returned image
 * will contain undefined data.
Havoc Pennington's avatar
Havoc Pennington committed
1151 1152 1153
 * 
 * Return value: a #GdkImage containing the contents of @drawable
 **/
Havoc Pennington's avatar
Havoc Pennington committed
1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164
GdkImage*
gdk_drawable_get_image (GdkDrawable *drawable,
                        gint         x,
                        gint         y,
                        gint         width,
                        gint         height)
{
  GdkDrawable *composite;
  gint composite_x_offset = 0;
  gint composite_y_offset = 0;
  GdkImage *retval;