The gdk-pixbuf Library
<<< Previous Page | Home | Up | Next Page >>>

# Drawables to Pixbufs

## Name

Drawables to Pixbufs -- Getting parts of a drawable's image data into a pixbuf.

## Synopsis

    #include <gdk-pixbuf/gdk-pixbuf.h>

    GdkPixbuf*  gdk_pixbuf_get_from_drawable    (GdkPixbuf *dest,
                                                 GdkDrawable *src,
                                                 GdkColormap *cmap,
                                                 int src_x,
                                                 int src_y,
                                                 int dest_x,
                                                 int dest_y,
                                                 int width,
                                                 int height);

## Description

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.

## Details

### gdk_pixbuf_get_from_drawable ()

    GdkPixbuf*  gdk_pixbuf_get_from_drawable    (GdkPixbuf *dest,
                                                 GdkDrawable *src,
                                                 GdkColormap *cmap,
                                                 int src_x,
                                                 int src_y,
                                                 int dest_x,
                                                 int dest_y,
                                                 int width,
                                                 int height);

Transfers image data from a Gdk drawable and converts it to an RGB(A) representation inside a GdkPixbuf.

If the drawable `src` is a pixmap, then a suitable colormap must be specified, since pixmaps are just blocks of pixel data without an associated colormap. If the drawable is a window, the `cmap` argument will be ignored and the window's own colormap will be used instead.

If the specified destination pixbuf `dest` is `NULL`, then this function will create an RGB pixbuf with 8 bits per channel and no alpha, with the same size specified by the `width` and `height` arguments. In this case, the `dest_x` and `dest_y` arguments must be specified as 0, otherwise the function will return `NULL`. If the specified destination pixbuf is not `NULL` and it contains alpha information, then the filled pixels will be set to full opacity.

If the specified drawable is a pixmap, then the requested source rectangle must be completely contained within the pixmap, otherwise the function will return `NULL`.

If the specified drawable is a window, then it must be viewable, i.e. all of its ancestors up to the root window must be mapped. Also, the specified source rectangle must be completely contained within the window and within the screen. If regions of the window are obscured by noninferior windows, the contents of those regions are undefined. The contents of regions obscured by inferior windows of a different depth than that of the source window will also be undefined.

`dest` : | Destination pixbuf, or `NULL` if a new pixbuf should be created.
`src` : | Source drawable.
`cmap` : | A colormap if `src` is a pixmap. If it is a window, this argument will be ignored.
`src_x` : | Source X coordinate within drawable.
`src_y` : | Source Y coordinate within drawable.
`dest_x` : | Destination X coordinate in pixbuf, or 0 if `dest` is `NULL`.
`dest_y` : | Destination Y coordinate in pixbuf, or 0 if `dest` is `NULL`.
`width` : | Width in pixels of region to get.
`height` : | Height in pixels of region to get.
Returns : | The same pixbuf as `dest` if it was non-`NULL`, or a newly-created pixbuf with a reference count of 1 if no destination pixbuf was specified; in the latter case, `NULL` will be returned if not enough memory could be allocated for the pixbuf to be created or if the image data could not be retrieved from the drawable.

## See Also

gdk_image_get().

<<< Previous Page | Home | Up | Next Page >>>
Scaling | Utilities