1 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Long_Description ##### -->
3 The functions in this section allow you to take the image data
4 from a GDK drawable and dump it into a #GdkPixbuf. This can be
5 used for screenshots and other special effects. Note that these
6 operations can be expensive, since the image data has to be
7 transferred from the X server to the client program and converted.
11 <!-- ##### SECTION ./tmpl/from-drawables.sgml:See_Also ##### -->
17 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Short_Description ##### -->
18 Getting parts of a drawable's image data into a pixbuf.
21 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Title ##### -->
25 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Long_Description ##### -->
27 This canvas item displays #GdkPixbuf images. It handles full
28 affine transformations in both GDK and antialiased modes, and also
29 supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
30 url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
31 translation semantics for absolute pixel values.
35 #GdkPixbuf structures may be shared among different pixbuf canvas
36 items; the pixbuf item uses #GdkPixbuf's reference counting
41 <title>Custom Scaling and Translation</title>
44 In addition to the normal affine transformations supported by
45 canvas items, the #GnomeCanvasPixbuf item supports independent
46 object arguments for scaling and translation. This is useful
47 for explicitly setting a size to which the pixbuf's image will
48 be scaled, and for specifying translation offsets that take
49 place in the item's local coordinate system.
53 By default, the pixbuf canvas item will attain the size in units
54 of the #GdkPixbuf it contains. If a #GnomeCanvasPixbuf is
55 configured to use a #GdkPixbuf that has a size of 300 by 200
56 pixels, then the pixbuf item will automatically obtain a size of
57 300 by 200 units in the item's local coordinate system. If the
58 item is transformed with a scaling transformation of (0.5, 2.0),
59 then the final image size will be of 150 by 400 pixels.
63 To set custom width and height values, you must set the <link
64 linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
65 linkend="GnomeCanvasPixbuf--height-set">height_set</link>
66 arguments to %TRUE, and then set the <link
67 linkend="GnomeCanvasPixbuf--width">width</link> or <link
68 linkend="GnomeCanvasPixbuf--height">height</link> arguments to
69 the desired values. The former two arguments control whether
70 the latter two are used when computing the final image's size;
71 they are both %FALSE by default so that the pixbuf item will
72 attain a size in units equal to the size in pixels of the
73 #GdkPixbuf that the item contains.
77 The custom translation offsets are controlled by the <link
78 linkend="GnomeCanvasPixbuf--x">x</link> and <link
79 linkend="GnomeCanvasPixbuf--y">y</link> arguments. The logical
80 upper-left vertex of the image will be translated by the
81 specified distance, aligned with the item's local coordinate
87 <title>Absolute Pixel Scaling and Translation</title>
90 The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
91 Graphics</ulink> specification (SVG) of the <ulink
92 url="http://www.w3.org">World Wide Web Consortium</ulink> also
93 allows images to be translated and scaled by absolute pixel
94 values that are independent of an item's normal affine
99 Normally, the pixbuf item's translation and scaling arguments
100 are interpreted in units, so they will be modified by the item's
101 affine transformation. The <link
102 linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
104 linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
106 linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
108 linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
109 object arguments can be used to modify this behavior. If one of
110 these arguments is %TRUE, then the corresponding scaling or
111 translation value will not be affected lengthwise by the pixbuf
112 item's affine transformation.
116 For example, consider a pixbuf item whose size is (300, 200).
117 If the item is modified with a scaling transformation of (0.5,
119 linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
120 is set to %TRUE, then the item will appear to be (300, 400)
121 pixels in size. This means that in this case the item's affine
122 transformation only applies to the height value, while the width
123 value is kept in absolute pixels.
127 Likewise, consider a pixbuf item whose (<link
128 linkend="GnomeCanvasPixbuf--x">x</link>, <link
129 linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
130 (30, 40). If the item is then modified by the same scaling
131 transformation of (0.5, 2.0) but the <link
132 linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
133 argument is set to %TRUE, then the image's upper-left corner
134 will appear to be at position (15, 40). In this case, the
135 affine transformation is applied only to the x offset, while the
136 y offset is kept in absolute pixels.
140 In short, these arguments control whether a particular dimension
141 of a pixbuf item is scaled or not in the normal way by the
142 item's affine transformation.
147 <title>Resource Management</title>
150 When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf
151 item will use by setting the <link
152 linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument, a
153 reference count will be added to that #GdkPixbuf structure.
154 When the pixbuf item no longer needs the #GdkPixbuf structure,
155 such as when the item is destroyed or when a new pixbuf
156 structure is passed to it, then the old #GdkPixbuf structure
157 will be automatically unreferenced.
161 This means that if an application just needs to load a pixbuf
162 image and set it into a pixbuf canvas item, it can do the
163 following to ‘forget’ about the pixbuf structure:
167 GnomeCanvasItem *item;
169 pixbuf = gdk_pixbuf_new_from_file ("foo.png");
170 g_assert (pixbuf != NULL);
172 item = gnome_canvas_item_new (gnome_canvas_root (my_canvas),
173 gnome_canvas_pixbuf_get_type (),
176 gdk_pixbuf_unref (pixbuf);
181 After this happens, the reference count of the pixbuf structure
182 will be 1: the gdk_pixbuf_new_from_file() function creates it
183 with a reference count of 1, then setting the <link
184 linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
185 the #GnomeCanvasPixbuf item increases it to 2, and then it is
186 decremented to 1 by the call to gdk_pixbuf_unref(). When the
187 canvas item is destroyed, it will automatically unreference the
188 pixbuf structure again, causing its reference count to drop to
189 zero and thus be freed.
194 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:See_Also ##### -->
196 #GnomeCanvas, #GdkPixbuf
200 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Short_Description ##### -->
201 Canvas item to display #GdkPixbuf images.
204 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Title ##### -->
208 <!-- ##### SECTION ./tmpl/rendering.sgml:Long_Description ##### -->
210 The &gdk-pixbuf; library provides several convenience functions to
211 render pixbufs to GDK drawables. It uses the GdkRGB to render the
216 At this point there is not a standard alpha channel extension for
217 the X Window System, so it is not possible to use full opacity
218 information when painting images to arbitrary drawables. The
219 &gdk-pixbuf; convenience functions will threshold the opacity
220 information to create a bi-level clipping mask (black and white),
221 and use that to draw the image onto a drawable.
226 Since these functions use GdkRGB for rendering, you must
227 initialize GdkRGB before using any of them. You can do this by
228 calling gdk_rgb_init() near the beginning of your program.
233 <!-- ##### SECTION ./tmpl/rendering.sgml:See_Also ##### -->
239 <!-- ##### SECTION ./tmpl/rendering.sgml:Short_Description ##### -->
240 Rendering a pixbuf to a GDK drawable.
243 <!-- ##### SECTION ./tmpl/rendering.sgml:Title ##### -->
247 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Long_Description ##### -->
249 The functions in this section allow you to take the image data
250 from an X drawable and dump it into a #GdkPixbuf. This can be
251 used for screenshots and other special effects. Note that these
252 operations can be expensive, since the image data has to be
253 transferred from the X server to the client program and converted.
257 These functions are analogous to those for the Gdk version of
262 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:See_Also ##### -->
268 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Short_Description ##### -->
269 Getting parts of an X drawable's image data into a pixbuf.
272 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Title ##### -->
273 X Drawables to Pixbufs
276 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Long_Description ##### -->
278 In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
279 package provides a small library that lets Xlib-only applications
280 use #GdkPixbuf structures and render them to X drawables. The
281 functions in this section are used to initialize the &gdk-pixbuf;
282 Xlib library. This library must be initialized near the beginning
283 or the program or before calling any of the other &gdk-pixbuf;
284 Xlib functions; it cannot be initialized automatically since
285 Xlib-only applications do not call gdk_rgb_init() like GNOME
290 <!-- ##### SECTION ./tmpl/xlib-init.sgml:See_Also ##### -->
296 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Short_Description ##### -->
297 Initializing the &gdk-pixbuf; Xlib library.
300 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Title ##### -->
301 &gdk-pixbuf; Xlib initialization
304 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Long_Description ##### -->
306 The &gdk-pixbuf; Xlib library provides several convenience
307 functions to render pixbufs to X drawables. It uses XlibRGB to
308 render the image data.
312 These functions are analogous to those for the Gdk version of
317 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:See_Also ##### -->
323 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Short_Description ##### -->
324 Rendering a pixbuf to an X drawable.
327 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Title ##### -->
331 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Long_Description ##### -->
333 The XlibRGB set of functions is a port of the GdkRGB library to
334 use plain Xlib and X drawables. You can use these functions to
335 render RGB buffers into drawables very quickly with high-quality
340 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:See_Also ##### -->
346 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Short_Description ##### -->
347 Functions for rendering RGB buffers to X drawables.
350 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Title ##### -->
354 <!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
356 Casts a #GtkObject to a #GdkPixbufLoader.
361 <!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
363 Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
368 <!-- ##### USER_FUNCTION GdkPixbufLastUnref ##### -->
370 A function of this type can be used to override the default
371 operation when a pixbuf loses its last reference, i.e. when
372 gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a
373 reference count of 1. This function should determine whether to
374 finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether
375 to just resume normal execution. The last unref handler for a
376 #GdkPixbuf can be set using the
377 gdk_pixbuf_set_last_unref_handler() function. By default, pixbufs
378 will be finalized automatically if no last unref handler has been
382 @pixbuf: The pixbuf that is losing its last reference.
383 @data: User closure data.
385 <!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
387 Indicates the height the pixbuf will be scaled to. This argument
388 will only be used if the <link
389 linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
390 is %TRUE. Works in the same way as the <link
391 linkend="GnomeCanvasPixbuf--width">width</link> argument.
395 <!-- ##### ARG GnomeCanvasPixbuf:height-in-pixels ##### -->
397 Works in the same way as the <link
398 linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
399 argument. The default is %FALSE.
403 <!-- ##### ARG GnomeCanvasPixbuf:height-pixels ##### -->
409 <!-- ##### ARG GnomeCanvasPixbuf:height-set ##### -->
411 Determines whether the <link
412 linkend="GnomeCanvasPixbuf--height">height</link> argument is
413 taken into account when scaling the pixbuf item. Works in the
414 same way as the <link
415 linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument.
416 The default is %FALSE.
420 <!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
422 Contains a pointer to a #GdkPixbuf structure that will be used by
423 the pixbuf canvas item as an image source. When a pixbuf is set
424 its reference count is incremented; if the pixbuf item kept a
425 pointer to another #GdkPixbuf structure, the reference count of
426 this structure will be decremented. Also, the GdkPixbuf's
427 reference count will automatically be decremented when the
428 #GnomeCanvasPixbuf item is destroyed. When a pixbuf is queried, a
429 reference count will not be added to the return value; you must do
430 this yourself if you intend to keep the pixbuf structure around.
434 <!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
436 Indicates the width the pixbuf will be scaled to. This argument
437 will only be used if the <link
438 linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
439 is %TRUE. If the <link
440 linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
441 argument is %FALSE, the width will be taken to be in canvas units,
442 and thus will be scaled along with the canvas item's affine
443 transformation. If width_in_pixels is %TRUE, the width will be
444 taken to be in pixels, and will visually remain a constant size
445 even if the item's affine transformation changes.
449 <!-- ##### ARG GnomeCanvasPixbuf:width-in-pixels ##### -->
451 If this argument is %TRUE, then the width of the pixbuf will be
452 considered to be in pixels, that is, it will not be visually
453 scaled even if the item's affine transformation changes. If this
454 is %FALSE, then the width of the pixbuf will be considered to be
455 in canvas units, and so will be scaled normally by affine
456 transformations. The default is %FALSE.
460 <!-- ##### ARG GnomeCanvasPixbuf:width-pixels ##### -->
466 <!-- ##### ARG GnomeCanvasPixbuf:width-set ##### -->
468 Determines whether the <link
469 linkend="GnomeCanvasPixbuf--width">width</link> argument is taken
470 into account when scaling the pixbuf item. If this argument is
471 %FALSE, then the width value of the pixbuf will be used instead.
472 This argument is %FALSE by default.
476 <!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
478 Indicates the horizontal translation offset of the pixbuf item's
479 image. This offset may not actually appear horizontal, since it
480 will be affected by the item's affine transformation. The default
485 <!-- ##### ARG GnomeCanvasPixbuf:x-in-pixels ##### -->
487 If this argument is %TRUE, the pixbuf's translation with respect
488 to its logical origin in item-relative coordinates will be in
489 pixels, that is, the visible offset will not change even if the
490 item's affine transformation changes. If it is %FALSE, the
491 pixbuf's translation will be taken to be in canvas units, and thus
492 will change along with the item's affine transformation. The
497 <!-- ##### ARG GnomeCanvasPixbuf:x-pixels ##### -->
503 <!-- ##### ARG GnomeCanvasPixbuf:x-set ##### -->
505 Determines whether the <link
506 linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
507 translate the pixbuf from its logical origin in item-relative
512 <!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
514 Indicates the vertical translation offset of the pixbuf item's
515 image. Works in the same way as the <link
516 linkend="GnomeCanvasPixbuf--x">x</link> argument. The default is
521 <!-- ##### ARG GnomeCanvasPixbuf:y-in-pixels ##### -->
523 Works in the same way as the <link
524 linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>
525 argument, but controls whether the <link
526 linkend="GnomeCanvasPixbuf--y">y</link> translation offset is
527 scaled or not. The default is %FALSE.
533 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
538 <!-- ##### ARG GnomeCanvasPixbuf:y-pixels ##### -->
544 <!-- ##### ARG GnomeCanvasPixbuf:y-set ##### -->
546 Determines whether the <link
547 linkend="GnomeCanvasPixbuf--y">y</link> argument is used to
548 translate the pixbuf from its logical origin in item-relative
549 coordinates. Works in the same way as the <link
550 linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument. The