PageRenderTime 33ms CodeModel.GetById 17ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/gdk/library/gdk_drawable.e

http://github.com/tybor/Liberty
Specman e | 554 lines | 101 code | 96 blank | 357 comment | 5 complexity | aa41d493aa861070b3d5b870128e7798 MD5 | raw file
  1indexing
  2	description: "GDK_DRAWABLE - Drawing Primitives ??????Functions for drawing points, lines, arcs, and text."
  3	copyright: "[
  4					Copyright (C) 2006 eiffel-libraries team, GTK+ team
  5					
  6					This library is free software; you can redistribute it and/or
  7					modify it under the terms of the GNU Lesser General Public License
  8					as published by the Free Software Foundation; either version 2.1 of
  9					the License, or (at your option) any later version.
 10					
 11					This library is distributed in the hope that it will be useful, but
 12					WITHOUT ANY WARRANTY; without even the implied warranty of
 13					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 14					Lesser General Public License for more details.
 15
 16					You should have received a copy of the GNU Lesser General Public
 17					License along with this library; if not, write to the Free Software
 18					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 19					02110-1301 USA
 20				]"
 21
 22deferred class GDK_DRAWABLE
 23	-- These functions provide support for drawing points, lines, arcs
 24	-- and text onto what are called 'drawables'. Drawables, as the
 25	-- name suggests, are things which support drawing onto them, and
 26	-- are either GdkWindow or GdkPixmap objects.
 27
 28	-- Many of the drawing operations take a GdkGC argument, which
 29	-- represents a graphics context. This GdkGC contains a number of
 30	-- drawing attributes such as foreground color, background color
 31	-- and line width, and is used to reduce the number of arguments
 32	-- needed for each drawing operation. See the Graphics Contexts
 33	-- section for more information.
 34
 35	-- Some of the drawing operations take Pango data structures like
 36	-- PangoContext, PangoLayout or PangoLayoutLine as arguments. If
 37	-- you're using GTK+, the ususal way to obtain these structures is
 38	-- via gtk_widget_create_pango_context() or
 39	-- gtk_widget_create_pango_layout().
 40
 41inherit G_OBJECT
 42
 43insert GDK_DRAWABLE_EXTERNALS
 44
 45feature
 46	context: CAIRO_CONTEXT is
 47    	-- A (newly allocated) context for drawing to drawable. 
 48	do
 49    	create Result.from_external_pointer (handle)
 50		-- Note: A CAIRO_CONTEXT will automatically call cairo_destroy when
 51		-- disposed. In fact, since it is a REFERENCE_COUNTE when disposed. In
 52		-- fact, since it is a REFERENCE_COUNTED, its memory will be handled by
 53		-- SmartEiffel garbage collector.
 54  	end	
 55	
 56
 57
 58	-- TODO: display: GDK_DISPLAY is
 59	-- the GdkDisplay associated with a GdkDrawable.
 60	-- do
 61	-- create Result.from_external_pointer (gdk_drawable_get_display (handle))
 62	-- end
 63	
 64	-- TODO: screen: GDK_SCREEN is
 65	-- the GdkScreen associated with a GdkDrawable.
 66	-- do
 67	-- create Result.from_external_pointer (gdk_drawable_get_screen (handle))
 68	-- end
 69	
 70	-- TODO: visual: GDK_VISUAL is
 71	-- the GdkVisual describing the pixel format of drawable.
 72	-- do
 73	-- create Result.from_external_pointer (gdk_drawable_get_visual (handle))
 74	-- end
 75
 76	-- TODO: gdk_drawable_set_colormap ()
 77
 78	-- void        gdk_drawable_set_colormap       (GdkDrawable *drawable,
 79	--                                              GdkColormap *colormap);
 80
 81	-- 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.
 82
 83	-- drawable : 	a GdkDrawable
 84	-- colormap : 	a GdkColormap
 85	-- gdk_drawable_get_colormap ()
 86
 87	-- GdkColormap* gdk_drawable_get_colormap      (GdkDrawable *drawable);
 88
 89	-- Gets the colormap for drawable, if one is set; returns NULL otherwise.
 90
 91	-- drawable : 	a GdkDrawable
 92	-- Returns : 	the colormap, or NULL
 93
 94	depth: INTEGER is
 95			-- the bit depth of the drawable, that is, the number of bits
 96			-- that make up a pixel in the drawable's visual. Examples
 97			-- are 8 bits per pixel, 24 bits per pixel, etc.
 98		do
 99			Result := gdk_drawable_get_depth (handle)
100		end
101
102	dimensions: TUPLE [INTEGER, INTEGER] is
103			-- width and height with the size of drawable. On the X11
104			-- platform, if drawable is a GdkWindow, the returned size is
105			-- the size reported in the most-recently-processed configure
106			-- event, rather than the current size on the X server.
107		local a_width, a_height: INTEGER
108		do
109			gdk_drawable_get_size (handle, $a_width, $a_height)
110			create Result.make_2 (a_width, a_height)
111		ensure not_void: Result /= Void
112		end
113
114	width: INTEGER is
115			-- width of the drawable. On the X11 platform, if drawable is
116			-- a GdkWindow, the returned size is the size reported in the
117			-- most-recently-processed configure event, rather than the
118			-- current size on the X server.
119		do
120			gdk_drawable_get_size (handle, $Result, default_pointer)
121		end
122
123	height: INTEGER is
124			-- height of the drawable. On the X11 platform, if drawable is
125			-- a GdkWindow, the returned size is the size reported in the
126			-- most-recently-processed configure event, rather than the
127			-- current size on the X server.
128		do
129			gdk_drawable_get_size (handle, default_pointer, $Result)
130		end
131
132	clip_region: GDK_REGION is
133			-- the region of a drawable that potentially can be written
134			-- to by drawing primitives. This region will not take into
135			-- account the clip region for the GC, and may also not take
136			-- into account other factors such as if the window is
137			-- obscured by other windows, but no area outside of this
138			-- region will be affected by drawing primitives.
139		do
140			create Result.from_external_pointer (gdk_drawable_get_clip_region (handle))
141		end
142
143	visible_region: GDK_REGION is
144			-- the region of a drawable that is potentially visible. This
145			-- does not necessarily take into account if the window is
146			-- obscured by other windows, but no area outside of this
147			-- region is visible.
148		do
149			create Result.from_external_pointer (gdk_drawable_get_visible_region (handle))
150		end
151	
152	draw_point (a_gc: GDK_GC; an_x, an_y: INTEGER) is
153			-- Draws a point, using the foreground color and other
154			-- attributes of the GDK_GC.
155		do
156			gdk_draw_point (handle, a_gc.handle, an_x, an_y)
157		end
158
159	-- gdk_draw_points ()
160
161	-- void        gdk_draw_points                 (GdkDrawable *drawable,
162	--                                              GdkGC *gc,
163	--                                              GdkPoint *points,
164	--                                              gint npoints);
165
166	-- Draws a number of points, using the foreground color and other attributes of the GdkGC.
167
168	-- drawable : 	a GdkDrawable (a GdkWindow or a GdkPixmap).
169	-- gc : 	a GdkGC.
170	-- points : 	an array of GdkPoint structures.
171	-- npoints : 	the number of points to be drawn.
172
173	draw_line (a_gc: GDK_GC; x1, y1, x2, y2: INTEGER) is
174			-- Draws a line, using the foreground color and other attributes
175			-- of the GdkGC.
176		do
177			gdk_draw_line (handle, a_gc.handle, x1, y1, x2, y2)
178		end
179
180	-- gdk_draw_lines ()
181
182	-- void        gdk_draw_lines                  (GdkDrawable *drawable,
183	--                                              GdkGC *gc,
184	--                                              GdkPoint *points,
185	--                                              gint npoints);
186
187	-- 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().
188
189	-- drawable : 	a GdkDrawable (a GdkWindow or a GdkPixmap).
190	-- gc : 	a GdkGC.
191	-- points : 	an array of GdkPoint structures specifying the endpoints of the
192	-- npoints : 	the size of the points array.
193	-- gdk_draw_pixbuf ()
194
195	-- void        gdk_draw_pixbuf                 (GdkDrawable *drawable,
196	--                                              GdkGC *gc,
197	--                                              GdkPixbuf *pixbuf,
198	--                                              gint src_x,
199	--                                              gint src_y,
200	--                                              gint dest_x,
201	--                                              gint dest_y,
202	--                                              gint width,
203	--                                              gint height,
204	--                                              GdkRgbDither dither,
205	--                                              gint x_dither,
206	--                                              gint y_dither);
207
208	-- Renders a rectangular portion of a pixbuf to a drawable. The destination drawable must have a colormap. All windows have a colormap, however, pixmaps 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().
209
210	-- On older X servers, rendering pixbufs with an alpha channel involves round trips to the X server, and may be somewhat slow.
211
212	-- The clip mask of gc is ignored, but clip rectangles and clip regions work fine.
213
214	-- drawable : 	Destination drawable.
215	-- gc : 	a GdkGC, used for clipping, or NULL
216	-- pixbuf : 	a GdkPixbuf
217	-- src_x : 	Source X coordinate within pixbuf.
218	-- src_y : 	Source Y coordinates within pixbuf.
219	-- dest_x : 	Destination X coordinate within drawable.
220	-- dest_y : 	Destination Y coordinate within drawable.
221	-- width : 	Width of region to render, in pixels, or -1 to use pixbuf width.
222	-- height : 	Height of region to render, in pixels, or -1 to use pixbuf height.
223	-- dither : 	Dithering mode for GdkRGB.
224	-- x_dither : 	X offset for dither.
225	-- y_dither : 	Y offset for dither.
226
227	-- Since 2.2
228	-- gdk_draw_segments ()
229
230	-- void        gdk_draw_segments               (GdkDrawable *drawable,
231	--                                              GdkGC *gc,
232	--                                              GdkSegment *segs,
233	--                                              gint nsegs);
234
235	-- Draws a number of unconnected lines.
236
237	-- drawable : 	a GdkDrawable (a GdkWindow or a GdkPixmap).
238	-- gc : 	a GdkGC.
239	-- segs : 	an array of GdkSegment structures specifying the start and end points of the lines to be drawn.
240	-- nsegs : 	the number of line segments to draw, i.e. the size of the segs array.
241	-- GdkSegment
242
243	-- typedef struct {
244	--   gint x1;
245	--   gint y1;
246	--   gint x2;
247	--   gint y2;
248	-- } GdkSegment;
249
250	-- Specifies the start and end point of a line for use by the gdk_draw_segments() function.
251	-- gint x1; 	the x coordinate of the start point.
252	-- gint y1; 	the y coordinate of the start point.
253	-- gint x2; 	the x coordinate of the end point.
254	-- gint y2; 	the y coordinate of the end point.
255	-- gdk_draw_rectangle ()
256
257	draw_rectangle (a_gc: GDK_GC; filled: BOOLEAN; an_x, an_y, a_width, a_height: INTEGER) is
258			-- Draws a rectangular outline or filled rectangle, using the
259			-- foreground color and other attributes of the GdkGC.
260			--
261			-- A rectangle drawn filled is 1 pixel smaller in both dimensions than
262			-- a rectangle outlined. Calling draw_rectangle (gc, True, 0, 0, 20, 20)
263			-- results in a filled rectangle 20 pixels wide and 20 pixels high.
264			-- Calling draw_rectangle (gc, False, 0, 0, 20, 20) results in an
265			-- outlined rectangle with corners at (0, 0), (0, 20), (20, 20),
266			-- and (20, 0), which makes it 21 pixels wide and 21 pixels high.
267		do
268			gdk_draw_rectangle (handle, a_gc.handle, filled.to_integer,
269								an_x, an_y, a_width, a_height)
270		end
271
272	draw_arc (a_gc: GDK_GC; a_filled: BOOLEAN; an_x, an_y,
273							 a_width, a_height, angle1, angle2: INTEGER) is
274			-- Draws an arc or a filled 'pie slice'. The arc is defined by
275			-- the bounding rectangle of the entire ellipse, and the start
276			-- and end angles of the part of the ellipse to be drawn.
277			--
278			-- a_filled:  TRUE if the arc should be filled, producing a 'pie slice'.
279			-- an_x:  the x coordinate of the left edge of the bounding rectangle.
280			-- an_y:  the y coordinate of the top edge of the bounding rectangle.
281			-- a_width:  the width of the bounding rectangle.
282			-- a_height:  the height of the bounding rectangle.
283			-- angle1:  the start angle of the arc, relative to the 3 o'clock
284			--          position, counter-clockwise, in 1/64ths of a degree.
285			-- angle2:  the end angle of the arc, relative to angle1, in
286			--          1/64ths of a degree.
287		do
288			gdk_draw_arc (handle, a_gc.handle, a_filled.to_integer, an_x, an_y,
289							a_width, a_height, angle1, angle2)
290		end
291
292	-- gdk_draw_polygon ()
293
294	-- void        gdk_draw_polygon                (GdkDrawable *drawable,
295	--                                              GdkGC *gc,
296	--                                              gboolean filled,
297	--                                              GdkPoint *points,
298	--                                              gint npoints);
299
300	-- Draws an outlined or filled polygon.
301
302	-- drawable : 	a GdkDrawable (a GdkWindow or a GdkPixmap).
303	-- gc : 	a GdkGC.
304	-- filled : 	TRUE if the polygon should be filled. The polygon is closed automatically, connecting the last point to the first point if necessary.
305	-- points : 	an array of GdkPoint structures specifying the points making up the polygon.
306	-- npoints : 	the number of points.
307	-- gdk_draw_trapezoids ()
308
309	-- void        gdk_draw_trapezoids             (GdkDrawable *drawable,
310	--                                              GdkGC *gc,
311	--                                              GdkTrapezoid *trapezoids,
312	--                                              gint n_trapezoids);
313
314	-- 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.
315
316	-- drawable : 	a GdkDrawable
317	-- gc : 	a GdkGC
318	-- trapezoids : 	an array of GdkTrapezoid structures
319	-- n_trapezoids : 	the number of trapezoids to draw
320
321	-- Since 2.6
322	-- GdkTrapezoid
323
324	-- typedef struct {
325	--   double y1, x11, x21, y2, x12, x22;
326	-- } GdkTrapezoid;
327
328	-- Specifies a trapezpoid for use by the gdk_draw_trapezoids(). The trapezoids used here have parallel, horizontal top and bottom edges.
329	-- double y1; 	the y coordinate of the start point.
330	-- double x11; 	the x coordinate of the top left corner
331	-- double x21; 	the x coordinate of the top right corner
332	-- double y2; 	the y coordinate of the end point.
333	-- double x12; 	the x coordinate of the bottom left corner
334	-- double x22; 	the x coordinate of the bottom right corner
335	-- gdk_draw_glyphs ()
336
337	-- void        gdk_draw_glyphs                 (GdkDrawable *drawable,
338	--                                              GdkGC *gc,
339	--                                              PangoFont *font,
340	--                                              gint x,
341	--                                              gint y,
342	--                                              PangoGlyphString *glyphs);
343
344	-- This is a low-level function; 99% of text rendering should be done using gdk_draw_layout() instead.
345
346	-- A glyph is a single image in a font. This function draws a sequence of 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.
347
348	-- drawable : 	a GdkDrawable
349	-- gc : 	a GdkGC
350	-- font : 	font to be used
351	-- x : 	X coordinate of baseline origin
352	-- y : 	Y coordinate of baseline origin
353	-- glyphs : 	the glyph string to draw
354	-- gdk_draw_glyphs_transformed ()
355
356	-- void        gdk_draw_glyphs_transformed     (GdkDrawable *drawable,
357	--                                              GdkGC *gc,
358	--                                              PangoMatrix *matrix,
359	--                                              PangoFont *font,
360	--                                              gint x,
361	--                                              gint y,
362	--                                              PangoGlyphString *glyphs);
363
364	-- 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.
365
366	-- See also gdk_draw_glyphs(), gdk_draw_layout().
367
368	-- drawable : 	a GdkDrawable
369	-- gc : 	a GdkGC
370	-- matrix : 	a PangoMatrix, or NULL to use an identity transformation
371	-- font : 	the font in which to draw the string
372	-- x : 	the x position of the start of the string (in Pango units in user space coordinates)
373	-- y : 	the y position of the baseline (in Pango units in user space coordinates)
374	-- glyphs : 	the glyph string to draw
375
376	-- Since 2.6
377	-- gdk_draw_layout_line ()
378
379	-- void        gdk_draw_layout_line            (GdkDrawable *drawable,
380	--                                              GdkGC *gc,
381	--                                              gint x,
382	--                                              gint y,
383	--                                              PangoLayoutLine *line);
384
385	-- Render a PangoLayoutLine onto an GDK drawable
386
387	-- If the layout's PangoContext has a transformation matrix set, then x and y specify the position of the left edge of the baseline (left is in before-tranform user coordinates) in after-transform device coordinates.
388
389	-- drawable : 	the drawable on which to draw the line
390	-- gc : 	base graphics to use
391	-- x : 	the x position of start of string (in pixels)
392	-- y : 	the y position of baseline (in pixels)
393	-- line : 	a PangoLayoutLine
394	-- gdk_draw_layout_line_with_colors ()
395
396	-- void        gdk_draw_layout_line_with_colors
397	--                                             (GdkDrawable *drawable,
398	--                                              GdkGC *gc,
399	--                                              gint x,
400	--                                              gint y,
401	--                                              PangoLayoutLine *line,
402	--                                              const GdkColor *foreground,
403	--                                              const GdkColor *background);
404
405	-- Render a PangoLayoutLine onto a GdkDrawable, overriding the layout's normal colors with foreground and/or background. foreground and background need not be allocated.
406
407	-- If the layout's PangoContext has a transformation matrix set, then x and y specify the position of the left edge of the baseline (left is in before-tranform user coordinates) in after-transform device coordinates.
408
409	-- drawable : 	the drawable on which to draw the line
410	-- gc : 	base graphics to use
411	-- x : 	the x position of start of string (in pixels)
412	-- y : 	the y position of baseline (in pixels)
413	-- line : 	a PangoLayoutLine
414	-- foreground : 	foreground override color, or NULL for none
415	-- background : 	background override color, or NULL for none
416
417
418	draw_layout (a_gc: GDK_GC; an_x, an_y: INTEGER; a_layout: PANGO_LAYOUT) is
419			-- Render a PangoLayout onto a GDK drawable
420			--
421			-- If the layout's PANGO_CONTEXT has a transformation matrix set,
422			-- then an_x and an_y specify the position of the top left corner
423			-- of the bounding box (in device space) of the transformed layout.
424			--
425			-- If you're using GTK+, the usual way to obtain a PANGO_LAYOUT is
426			-- my_widget.create_pango_layout
427		require
428			a_gc /= Void
429			a_layout /= Void
430		do
431			gdk_draw_layout (handle, a_gc.handle, an_x, an_y, a_layout.handle)
432		end
433
434	draw_layout_with_colors (a_gc: GDK_GC; an_x, an_y: INTEGER;
435				a_layout: PANGO_LAYOUT; a_foreground, a_background: GDK_COLOR) is
436			-- Render a PANGO_LAYOUT onto a GDK_DRAWABLE, overriding the
437			-- layout's normal colors with a_foreground and/or a_background.
438			-- a_foreground and a_background need not be allocated.
439			--
440			-- If the layout's PANGO_CONTEXT has a transformation matrix set,
441			-- then an_x and an_y specify the position of the top left corner
442			-- of the bounding box (in device space) of the transformed layout.
443			--
444			-- If you're using GTK+, the ususal way to obtain a PANGO_LAYOUT
445			-- is my_widget.create_pango_layout.
446		require
447			a_gc /= Void
448			a_layout /= Void
449		local
450			fg_ptr, bg_ptr: POINTER
451		do
452			if a_foreground /= Void then fg_ptr := a_foreground.handle end
453			if a_background /= Void then bg_ptr := a_background.handle end
454			gdk_draw_layout_with_colors (handle, a_gc.handle, an_x, an_y,
455									a_layout.handle, fg_ptr, bg_ptr)
456		end
457
458	draw_drawable (a_gc: GDK_GC; a_drawable: GDK_DRAWABLE; xsrc, ysrc, xdest,
459					ydest, a_width, a_height: INTEGER) is
460			-- Copies the <width x height> region of a_drawable at coordinates
461			-- (xsrc, ysrc) to coordinates (xdest, ydest) in Current.
462			-- a_width and/or a_height may be given as -1, in which case the
463			-- entire a_drawable drawable will be copied.
464			--
465			-- Most fields in a_gc are not used for this operation, but notably
466			-- the clip mask or clip region will be honored.
467			--
468			-- The source and destination drawables must have the same visual
469			-- and colormap, or errors will result. (On X11, failure to match
470			-- visual/colormap results in a BadMatch error from the X server.)
471			-- A common cause of this problem is an attempt to draw a bitmap
472			-- to a color drawable. The way to draw a bitmap is to set the
473			-- bitmap as the stipple on the GdkGC, set the fill mode to
474			-- GDK_STIPPLED, and then draw the rectangle.
475		require
476			a_gc /= Void
477			a_drawable /= Void
478		do
479			gdk_draw_drawable (handle, a_gc.handle, a_drawable.handle,
480								xsrc, ysrc, xdest, ydest, a_width, a_height)
481		end
482
483	-- gdk_draw_image ()
484
485	-- void        gdk_draw_image                  (GdkDrawable *drawable,
486	--                                              GdkGC *gc,
487	--                                              GdkImage *image,
488	--                                              gint xsrc,
489	--                                              gint ysrc,
490	--                                              gint xdest,
491	--                                              gint ydest,
492	--                                              gint width,
493	--                                              gint height);
494
495	-- Draws a GdkImage onto a drawable. The depth of the GdkImage must match the depth of the GdkDrawable.
496
497	-- drawable : 	a GdkDrawable (a GdkWindow or a GdkPixmap).
498	-- gc : 	a GdkGC.
499	-- image : 	the GdkImage to draw.
500	-- xsrc : 	the left edge of the source rectangle within image.
501	-- ysrc : 	the top of the source rectangle within image.
502	-- xdest : 	the x coordinate of the destination within drawable.
503	-- ydest : 	the y coordinate of the destination within drawable.
504	-- width : 	the width of the area to be copied, or -1 to make the area extend to the right edge of image.
505	-- height : 	the height of the area to be copied, or -1 to make the area extend to the bottom edge of image.
506	-- gdk_drawable_get_image ()
507
508	-- GdkImage*   gdk_drawable_get_image          (GdkDrawable *drawable,
509	--                                              gint x,
510	--                                              gint y,
511	--                                              gint width,
512	--                                              gint height);
513
514	-- 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.
515
516	-- x, y, width, and height define the region of drawable to obtain as an image.
517
518	-- 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.
519
520	-- 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.
521
522	-- If the source drawable is a GdkWindow and partially offscreen or obscured, then the obscured portions of the returned image will contain undefined data.
523
524	-- drawable : 	a GdkDrawable
525	-- x : 	x coordinate on drawable
526	-- y : 	y coordinate on drawable
527	-- width : 	width of region to get
528	-- height : 	height or region to get
529	-- Returns : 	a GdkImage containing the contents of drawable
530	-- gdk_drawable_copy_to_image ()
531
532	-- GdkImage*   gdk_drawable_copy_to_image      (GdkDrawable *drawable,
533	--                                              GdkImage *image,
534	--                                              gint src_x,
535	--                                              gint src_y,
536	--                                              gint dest_x,
537	--                                              gint dest_y,
538	--                                              gint width,
539	--                                              gint height);
540
541	-- 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.
542
543	-- drawable : 	a GdkDrawable
544	-- image : 	a GdkDrawable, or NULL if a new image should be created.
545	-- src_x : 	x coordinate on drawable
546	-- src_y : 	y coordinate on drawable
547	-- dest_x : 	x coordinate within image. Must be 0 if image is NULL
548	-- dest_y : 	y coordinate within image. Must be 0 if image is NULL
549	-- width : 	width of region to get
550	-- height : 	height or region to get
551	-- Returns : 	image, or a new a GdkImage containing the contents of drawable
552
553	-- Since 2.4
554end