The functions in this section allow you to take the image data from a GDK drawable and dump it into a #GdkPixbuf. This can be used for screenshots and other special effects. Note that these operations can be expensive, since the image data has to be transferred from the X server to the client program and converted. gdk_image_get(). Getting parts of a drawable's image data into a pixbuf. Drawables to Pixbufs This canvas item displays #GdkPixbuf images. It handles full affine transformations in both GDK and antialiased modes, and also supports the W3C's SVG-like scaling and translation semantics for absolute pixel values. #GdkPixbuf structures may be shared among different pixbuf canvas items; the pixbuf item uses #GdkPixbuf's reference counting functions for this. In addition to the normal affine transformations supported by canvas items, the #GnomeCanvasPixbuf item supports independent object arguments for scaling and translation. This is useful for explicitly setting a size to which the pixbuf's image will be scaled, and for specifying translation offsets that take place in the item's local coordinate system. By default, the pixbuf canvas item will attain the size in units of the #GdkPixbuf it contains. If a #GnomeCanvasPixbuf is configured to use a #GdkPixbuf that has a size of 300 by 200 pixels, then the pixbuf item will automatically obtain a size of 300 by 200 units in the item's local coordinate system. If the item is transformed with a scaling transformation of (0.5, 2.0), then the final image size will be of 150 by 400 pixels. To set custom width and height values, you must set the width_set or height_set arguments to %TRUE, and then set the width or height arguments to the desired values. The former two arguments control whether the latter two are used when computing the final image's size; they are both %FALSE by default so that the pixbuf item will attain a size in units equal to the size in pixels of the #GdkPixbuf that the item contains. The custom translation offsets are controlled by the x and y arguments. The logical upper-left vertex of the image will be translated by the specified distance, aligned with the item's local coordinate system. The Scalable Vector Graphics specification (SVG) of the World Wide Web Consortium also allows images to be translated and scaled by absolute pixel values that are independent of an item's normal affine transformation. Normally, the pixbuf item's translation and scaling arguments are interpreted in units, so they will be modified by the item's affine transformation. The width_in_pixels, height_in_pixels, x_in_pixels, and y_in_pixels object arguments can be used to modify this behavior. If one of these arguments is %TRUE, then the corresponding scaling or translation value will not be affected lengthwise by the pixbuf item's affine transformation. For example, consider a pixbuf item whose size is (300, 200). If the item is modified with a scaling transformation of (0.5, 2.0) but the width_in_pixels is set to %TRUE, then the item will appear to be (300, 400) pixels in size. This means that in this case the item's affine transformation only applies to the height value, while the width value is kept in absolute pixels. Likewise, consider a pixbuf item whose (x, y) arguments are set to (30, 40). If the item is then modified by the same scaling transformation of (0.5, 2.0) but the y_in_pixels argument is set to %TRUE, then the image's upper-left corner will appear to be at position (15, 40). In this case, the affine transformation is applied only to the x offset, while the y offset is kept in absolute pixels. In short, these arguments control whether a particular dimension of a pixbuf item is scaled or not in the normal way by the item's affine transformation. When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf item will use by setting the pixbuf argument, a reference count will be added to that #GdkPixbuf structure. When the pixbuf item no longer needs the #GdkPixbuf structure, such as when the item is destroyed or when a new pixbuf structure is passed to it, then the old #GdkPixbuf structure will be automatically unreferenced. This means that if an application just needs to load a pixbuf image and set it into a pixbuf canvas item, it can do the following to ‘forget’ about the pixbuf structure: GdkPixbuf *pixbuf; GnomeCanvasItem *item; pixbuf = gdk_pixbuf_new_from_file ("foo.png"); g_assert (pixbuf != NULL); item = gnome_canvas_item_new (gnome_canvas_root (my_canvas), gnome_canvas_pixbuf_get_type (), "pixbuf", pixbuf, NULL); gdk_pixbuf_unref (pixbuf); After this happens, the reference count of the pixbuf structure will be 1: the gdk_pixbuf_new_from_file() function creates it with a reference count of 1, then setting the pixbuf argument of the #GnomeCanvasPixbuf item increases it to 2, and then it is decremented to 1 by the call to gdk_pixbuf_unref(). When the canvas item is destroyed, it will automatically unreference the pixbuf structure again, causing its reference count to drop to zero and thus be freed. #GnomeCanvas, #GdkPixbuf Canvas item to display #GdkPixbuf images. GnomeCanvasPixbuf The &gdk-pixbuf; library provides several convenience functions to render pixbufs to GDK drawables. It uses the GdkRGB to render the image data. At this point there is not a standard alpha channel extension for the X Window System, so it is not possible to use full opacity information when painting images to arbitrary drawables. The &gdk-pixbuf; convenience functions will threshold the opacity information to create a bi-level clipping mask (black and white), and use that to draw the image onto a drawable. Since these functions use GdkRGB for rendering, you must initialize GdkRGB before using any of them. You can do this by calling gdk_rgb_init() near the beginning of your program. GdkRGB Rendering a pixbuf to a GDK drawable. Rendering The functions in this section allow you to take the image data from an X drawable and dump it into a #GdkPixbuf. This can be used for screenshots and other special effects. Note that these operations can be expensive, since the image data has to be transferred from the X server to the client program and converted. These functions are analogous to those for the Gdk version of &gdk-pixbuf;. Getting parts of an X drawable's image data into a pixbuf. X Drawables to Pixbufs In addition to the normal Gdk-specific functions, the &gdk-pixbuf; package provides a small library that lets Xlib-only applications use #GdkPixbuf structures and render them to X drawables. The functions in this section are used to initialize the &gdk-pixbuf; Xlib library. This library must be initialized near the beginning or the program or before calling any of the other &gdk-pixbuf; Xlib functions; it cannot be initialized automatically since Xlib-only applications do not call gdk_rgb_init() like GNOME applications do. XlibRGB Initializing the &gdk-pixbuf; Xlib library. &gdk-pixbuf; Xlib initialization The &gdk-pixbuf; Xlib library provides several convenience functions to render pixbufs to X drawables. It uses XlibRGB to render the image data. These functions are analogous to those for the Gdk version of &gdk-pixbuf;. Rendering a pixbuf to an X drawable. Xlib Rendering The XlibRGB set of functions is a port of the GdkRGB library to use plain Xlib and X drawables. You can use these functions to render RGB buffers into drawables very quickly with high-quality dithering. GdkRGB Functions for rendering RGB buffers to X drawables. XlibRGB Casts a #GtkObject to a #GdkPixbufLoader. @obj: A GTK+ object. Casts a #GtkOjbect to a #GnomeCanvasPixbuf. @obj: A GTK+ object. A function of this type can be used to override the default operation when a pixbuf loses its last reference, i.e. when gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a reference count of 1. This function should determine whether to finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether to just resume normal execution. The last unref handler for a #GdkPixbuf can be set using the gdk_pixbuf_set_last_unref_handler() function. By default, pixbufs will be finalized automatically if no last unref handler has been defined. @pixbuf: The pixbuf that is losing its last reference. @data: User closure data. Indicates the height the pixbuf will be scaled to. This argument will only be used if the height_set argument is %TRUE. Works in the same way as the width argument. Works in the same way as the width_in_pixels argument. The default is %FALSE. Determines whether the height argument is taken into account when scaling the pixbuf item. Works in the same way as the width_set argument. The default is %FALSE. Contains a pointer to a #GdkPixbuf structure that will be used by the pixbuf canvas item as an image source. When a pixbuf is set its reference count is incremented; if the pixbuf item kept a pointer to another #GdkPixbuf structure, the reference count of this structure will be decremented. Also, the GdkPixbuf's reference count will automatically be decremented when the #GnomeCanvasPixbuf item is destroyed. When a pixbuf is queried, a reference count will not be added to the return value; you must do this yourself if you intend to keep the pixbuf structure around. Indicates the width the pixbuf will be scaled to. This argument will only be used if the width_set argument is %TRUE. If the width_in_pixels argument is %FALSE, the width will be taken to be in canvas units, and thus will be scaled along with the canvas item's affine transformation. If width_in_pixels is %TRUE, the width will be taken to be in pixels, and will visually remain a constant size even if the item's affine transformation changes. If this argument is %TRUE, then the width of the pixbuf will be considered to be in pixels, that is, it will not be visually scaled even if the item's affine transformation changes. If this is %FALSE, then the width of the pixbuf will be considered to be in canvas units, and so will be scaled normally by affine transformations. The default is %FALSE. Determines whether the width argument is taken into account when scaling the pixbuf item. If this argument is %FALSE, then the width value of the pixbuf will be used instead. This argument is %FALSE by default. Indicates the horizontal translation offset of the pixbuf item's image. This offset may not actually appear horizontal, since it will be affected by the item's affine transformation. The default is 0.0. If this argument is %TRUE, the pixbuf's translation with respect to its logical origin in item-relative coordinates will be in pixels, that is, the visible offset will not change even if the item's affine transformation changes. If it is %FALSE, the pixbuf's translation will be taken to be in canvas units, and thus will change along with the item's affine transformation. The default is %FALSE. Determines whether the x argument is used to translate the pixbuf from its logical origin in item-relative coordinates. Indicates the vertical translation offset of the pixbuf item's image. Works in the same way as the x argument. The default is 0.0. Works in the same way as the x_in_pixels argument, but controls whether the y translation offset is scaled or not. The default is %FALSE. Determines whether the y argument is used to translate the pixbuf from its logical origin in item-relative coordinates. Works in the same way as the x_set argument. The default is %FALSE. @inline_pixbuf: @copy_pixels: @length: @error: @Returns: