gtk.gdk.Pixbuf
Prev | The gtk.gdk Class Reference | Next

## gtk.gdk.Pixbuf

gtk.gdk.Pixbuf — an object containing a client side image.

## Synopsis

    class gtk.gdk.Pixbuf(gobject.GObject):
        gtk.gdk.Pixbuf(colorspace, has_alpha, bits_per_sample, width, height)
        def render_to_drawable(drawable, gc, src_x, src_y, dest_x, dest_y, width, height, dither, x_dither, y_dither)
        def render_to_drawable_alpha(drawable, src_x, src_y, dest_x, dest_y, width, height, alpha_mode, alpha_threshold, dither, x_dither, y_dither)
        def render_pixmap_and_mask(alpha_threshold=127)
        def get_from_drawable(src, cmap, src_x, src_y, dest_x, dest_y, width, height)
        def get_from_image(src, cmap, src_x, src_y, dest_x, dest_y, width, height)
        def get_colorspace()
        def get_n_channels()
        def get_has_alpha()
        def get_bits_per_sample()
        def get_pixels()
        def get_width()
        def get_height()
        def get_rowstride()
        def get_option(key)
        def copy()
        def fill(pixel)
        def save(filename, type, options=None)
        def save_to_callback(save_func, type, options=None, user_data=None)
        def add_alpha(substitute_color, r, g, b)
        def copy_area(src_x, src_y, width, height, dest_pixbuf, dest_x, dest_y)
        def saturate_and_pixelate(dest, saturation, pixelate)
        def scale(dest, dest_x, dest_y, dest_width, dest_height, offset_x, offset_y, scale_x, scale_y, interp_type)
        def composite(dest, dest_x, dest_y, dest_width, dest_height, offset_x, offset_y, scale_x, scale_y, interp_type, overall_alpha)
        def composite_color(dest, dest_x, dest_y, dest_width, dest_height, offset_x, offset_y, scale_x, scale_y, interp_type, overall_alpha, check_x, check_y, check_size, color1, color2)
        def scale_simple(dest_width, dest_height, interp_type)
        def composite_color_simple(dest_width, dest_height, interp_type, overall_alpha, check_size, color1, color2)
        def get_pixels_array()
        def subpixbuf(src_x, src_y, width, height)
        def rotate_simple(angle)

    Functions

        def gtk.gdk.pixbuf_new_from_file(filename)
        def gtk.gdk.pixbuf_new_from_file_at_size(filename, width, height)
        def gtk.gdk.pixbuf_new_from_data(data, colorspace, has_alpha, bits_per_sample, width, height, rowstride)
        def gtk.gdk.pixbuf_new_from_array(array, colorspace, bits_per_sample)
        def gtk.gdk.pixbuf_new_from_xpm_data(data)
        def gtk.gdk.pixbuf_new_from_inline(data_length, data, copy_pixels)
        def gtk.gdk.pixbuf_get_formats()
        def gtk.gdk.pixbuf_get_file_info(filename)

## Ancestry

    +-- gobject.GObject
      +-- gtk.gdk.Pixbuf

## Attributes

"pixel_array" | Read | A numeric array containing the pixel values of the `gtk.gdk.Pixbuf`. The contents of the numeric array can be changed even though the array is read-only. However you cannot change the pixel data of pixbufs that are backed by a const string such as stock icon pixbufs. `PyGTK` must be compiled with Numeric Python support for this to work.

## Properties

"bits-per-sample" | Read-Write-Construct Only | The number of bits per sample. Available in GTK+ 2.4 and above.
"colorspace" | Read-Write-Construct Only | The colorspace in which the samples are interpreted.Available in GTK+ 2.4 and above.
"has-alpha" | Read-Write-Construct Only | If `True`,the pixbuf has an alpha channel. Available in GTK+ 2.4 and above.
"height" | Read-Write-Construct Only | The number of rows of the pixbuf. Available in GTK+ 2.4 and above.
"n-channels" | Read-Write-Construct Only | The number of samples per pixel. Available in GTK+ 2.4 and above.
"pixels" | Read-Write-Construct Only | A pointer to the pixel data of the pixbuf. Available in GTK+ 2.4 and above.
"rowstride" | Read-Write-Construct Only | The number of bytes between the start of a row and the start of the next row. Available in GTK+ 2.4 and above.
"width" | Read-Write-Construct Only | The number of columns of the pixbuf. Available in GTK+ 2.4 and above.

## Description

A `gtk.gdk.Pixbuf` object contains the data that describes an image using client side resources. By contrast a `gtk.gdk.Pixmap` uses server side resources to hold image data. Manipulating the image data in a `gtk.gdk.Pixmap` may involve round trip transfers between a client and a server in X11 while manipulating image data in a `gtk.gdk.Pixbuf` involves only client side operations. Therefore using `gtk.gdk.Pixbuf` objects may be more efficient than using `gtk.gdk.Pixmap` objects if a lot of image manipulation is necessary.

In addition to the methods associated with a `gtk.gdk.Pixbuf` object there are a number of functions that can be used to create `gtk.gdk.Pixbuf` objects from file and inline data.

## Constructor

        gtk.gdk.Pixbuf(colorspace, has_alpha, bits_per_sample, width, height)

`colorspace` : | the color space for the image - currently only `gtk.gdk.COLORSPACE_RGB`.
`has_alpha` : | if `True` the image will have transparency information.
`bits_per_sample` : | the number of bits per color sample - currently must be 8.
`width` : | the width of image in pixels.
`height` : | the height of image in pixels.
Returns : | a newly-created `gtk.gdk.Pixbuf`.

Creates a new `gtk.gdk.Pixbuf` structure and allocates a buffer for it. The buffer has an optimal rowstride. Note that the buffer is not cleared; you will have to fill it completely yourself. The size of the image is specified by `width` and `height`.

## Methods

### gtk.gdk.Pixbuf.render_to_drawable

        def render_to_drawable(drawable, gc, src_x, src_y, dest_x, dest_y, width, height, dither, x_dither, y_dither)

`drawable` : | the destination `gtk.gdk.Drawable`.
`gc` : | the `gtk.gdk.GC` used for rendering.
`src_x` : | the X coordinate within the pixbuf.
`src_y` : | the Y coordinate within the pixbuf.
`dest_x` : | the X coordinate within `drawable`.
`dest_y` : | the Y coordinate within `drawable`.
`width` : | the width of region to render, in pixels, or -1 to use pixbuf width
`height` : | the height of region to render, in pixels, or -1 to use pixbuf height
`dither` : | the dithering mode.
`x_dither` : | the X offset for dithering.
`y_dither` : | the Y offset for dithering.

### Warning

This method is deprecated in PyGTK 2.2 and above. Use the `gtk.gdk.Drawable.draw_pixbuf`() method instead.

The `render_to_drawable`() method renders a rectangular portion of the pixbuf to a `gtk.gdk.Drawable` specified by `drawable` while using the `gtk.gdk.GC` specified by `gc`. This is done using GdkRGB, so the specified drawable must have the GdkRGB visual and colormap. Note that this method will ignore the opacity information for images with an alpha channel; the `gtk.gdk.GC` must already have the clipping mask set if you want transparent regions to show through.

The dither offset is important when re-rendering partial regions of an image to a rendered version of the full image, or when the offsets to a base position change, as in scrolling. The dither matrix has to be shifted for consistent visual results. If you do not have any of these cases, the dither offsets can be both zero.

### gtk.gdk.Pixbuf.render_to_drawable_alpha

        def render_to_drawable_alpha(drawable, src_x, src_y, dest_x, dest_y, width, height, alpha_mode, alpha_threshold, dither, x_dither, y_dither)

`drawable` : | the destination `gtk.gdk.Drawable`.
`gc` : | the `gtk.gdk.GC` used for rendering.
`src_x` : | the X coordinate within the pixbuf.
`src_y` : | the Y coordinate within the pixbuf.
`dest_x` : | the X coordinate within `drawable`.
`dest_y` : | the Y coordinate within `drawable`.
`width` : | the width of region to render, in pixels, or -1 to use pixbuf width
`height` : | the height of region to render, in pixels, or -1 to use pixbuf height
`alpha_mode` : | Ignored. Present for backward compatibility.
`alpha_threshold` : | Ignored. Present for backward compatibility
`dither` : | the dithering mode.
`x_dither` : | the X offset for dithering.
`y_dither` : | the Y offset for dithering.

### Warning

This method is deprecated in PyGTK 2.2 and above. Use the `gtk.gdk.Drawable.draw_pixbuf`() method instead.

The `render_to_drawable_alpha`() method renders a rectangular portion of the pixbuf to a `gtk.gdk.Drawable` specified by `drawable`. `drawable` must have a colormap. All windows have a colormap; however, pixmaps only have colormap by default if they were created with a window argument.specifying a `gtk.gdk.Window`. Otherwise a colormap must be set on them with the `gtk.gdk.Drawable.set_colormap`() method. On older X servers, rendering pixbufs with an alpha channel involves round trips to the X server, and may be somewhat slow.

### gtk.gdk.Pixbuf.render_pixmap_and_mask

        def render_pixmap_and_mask(alpha_threshold=127)

`alpha_threshold` : | the threshold value for opacity values.
Returns : | a tuple containing the created pixmap and mask.

The `render_to_pixmap_and_mask`() method returns a tuple containing a pixmap and a mask bitmap that the pixbuf and its corresponding thresholded alpha mask are rendered to. This is merely a convenience method; applications that need to render pixbufs with dither offsets or to specific drawables should use the `render_to_drawable_alpha`() or `render_to_drawable`() methods. If the pixbuf does not have an alpha channel, then the mask returned will be None.

### gtk.gdk.Pixbuf.get_from_drawable

        def get_from_drawable(src, cmap, src_x, src_y, dest_x, dest_y, width, height)

`src` : | the source `gtk.gdk.Drawable`.
`cmap` : | a colormap if `src` doesn't have one set.
`src_x` : | the X coordinate within `drawable`.
`src_y` : | the Y coordinate within `drawable`.
`dest_x` : | the X coordinate in the pixbuf.
`dest_y` : | the Y coordinate in the pixbuf.
`width` : | the width in pixels of the region to get.
`height` : | the height in pixels of the region to get.
Returns : | the pixbuf or `None` on error

The `get_from_drawable`() method transfers image data from the `gtk.gdk.Drawable` specified by `src` and converts it to an RGB(A) representation inside a `gtk.gdk.Pixbuf`. In other words, copies image data from a server-side drawable to a client-side RGB(A) buffer. This allows you to efficiently read individual pixels on the client side. If `src` has no colormap (the `gtk.gdk.Drawable.get_colormap`() method returns `None`), then a suitable colormap must be specified as `cmap`. Typically a `gtk.gdk.Window` or a pixmap created by passing a `gtk.gdk.Window` to `gtk.gdk.Pixmap()` will already have a colormap associated with it. If `src` has a colormap, the `cmap` argument will be ignored. If `src` is a bitmap (1 bit per pixel pixmap), then a colormap is not required; pixels with a value of 1 are assumed to be white, and pixels with a value of 0 are assumed to be black. For taking screenshots, the `gtk.gdk.colormap_get_system`() function returns the correct colormap to use.

If `src` is a pixmap, then the requested source rectangle must be completely contained within the pixmap, otherwise the function will return `None`. For pixmaps only (not for windows) passing -1 for `width` or `height` is allowed to mean the full width or height of the pixmap. If `src` is a window, and the window is off the screen, then there is no image data in the obscured/offscreen regions to be placed in the pixbuf. The contents of portions of the pixbuf corresponding to the offscreen region are undefined.

If the window you're obtaining data from is partially obscured by other windows, then the contents of the pixbuf areas corresponding to the obscured regions are undefined. If the target drawable is not mapped (typically because it's iconified/minimized or not on the current workspace), `None` will be returned. If memory can't be allocated for the return value, `None` will be returned instead. (In short, there are several ways this method can fail, and if it fails it returns `None`; so check the return value.)

This method calls the `gtk.gdk.Drawable.get_image`() method internally and converts the resulting image to a `gtk.gdk.Pixbuf`, so the documentation for the `gtk.gdk.Drawable.get_image`() method may also be helpful.

### gtk.gdk.Pixbuf.get_from_image

        def get_from_image(src, cmap, src_x, src_y, dest_x, dest_y, width, height)

`src` : | the source `gtk.gdk.Image`.
`cmap` : | a colormap if `src` doesn't have one set or `None`.
`src_x` : | the X coordinate within `src`.
`src_y` : | the Y coordinate within `src`.
`dest_x` : | the X coordinate in the pixbuf.
`dest_y` : | the Y coordinate in the pixbuf.
`width` : | the width in pixels of the region to get.
`height` : | the height in pixels of the region to get.
Returns : | the pixbuf or `None` on error

The `get_from_image`() method is the same as the `get_from_drawable`() method but gets the pixbuf from the `gtk.gdk.Image` specified by `src`.

### gtk.gdk.Pixbuf.get_colorspace

        def get_colorspace()

Returns : | the color space.

The `get_colorspace`() method returns the color space of the pixbuf.

### gtk.gdk.Pixbuf.get_n_channels

        def get_n_channels()

Returns : | the number of channels.

The `get_n_channels`() method returns the number of channels of a pixbuf.

### gtk.gdk.Pixbuf.get_has_alpha

        def get_has_alpha()

Returns : | `True` if the pixbuf has an alpha channel.

The `get_has_alpha`() method returns `True` if the pixbuf has an alpha channel (opacity information).

### gtk.gdk.Pixbuf.get_bits_per_sample

        def get_bits_per_sample()

Returns : | the number of bits per color sample.

The `get_bits_per_sample`() method returns the number of bits per color sample in a pixbuf.

### gtk.gdk.Pixbuf.get_pixels

        def get_pixels()

Returns : | a string containing the pixel data of the pixbuf

The `get_pixels`() method returns a sting containing the pixel data of the pixbuf.

### gtk.gdk.Pixbuf.get_width

        def get_width()

Returns : | the width in pixels.

The `get_width`() method returns the width of the pixbuf.

### gtk.gdk.Pixbuf.get_height

        def get_height()

Returns : | the height in pixels.

The `get_height`() method returns the height of the pixbuf.

### gtk.gdk.Pixbuf.get_rowstride

        def get_rowstride()

Returns : | the number of bytes between rows.

The `get_rowstride`() method returns the rowstride of a pixbuf, which is the number of bytes between rows.

### gtk.gdk.Pixbuf.get_option

        def get_option(key)

`key` : | a key string
Returns : | the value associated with `key`

The `get_option`() method looks up `key` in the list of options that may have been attached to the pixbuf when it was loaded.

### gtk.gdk.Pixbuf.copy

        def copy()

Returns : | A newly-created pixbuf or `None` if not enough memory could be allocated.

The `copy`() method returns a new `gtk.gdk.Pixbuf` with a copy of the data in the pixbuf.

### gtk.gdk.Pixbuf.fill

        def fill(pixel)

`pixel` : | the RGBA pixel to clear to (0xffffffff is opaque white, 0x00000000 transparent black)

The `fill`() method clears the pixbuf to the RGBA value specified by `pixel`, converting the RGBA value into the pixbuf's pixel format. The alpha will be ignored if the pixbuf doesn't have an alpha channel.

### gtk.gdk.Pixbuf.save

        def save(filename, type, options=None)

`filename` : | the name of file to save.
`type` : | the name of the file format.
`options` : | a Python dict containing key-value string pairs or `None`

The `save`() method saves the pixbuf to a file in the format specified by `type`, which may be "jpeg" or "png". If `options` is not `None` it should be a Python dict containing key-value string pairs that modify the save parameters. For example:

      pixbuf.save(filename, "jpeg", {"quality":"100"})

Currently only a few parameters exist. JPEG images can be saved with a "quality" parameter; its value should be in the range [0,100]. Text chunks can be attached to PNG images by specifying parameters of the form "tEXt::key", where key is an ASCII string of length 1-79. Note however that PNG text chunks are stored in ISO-8859-1 encoding, so you can only set texts that can be represented in this encoding. The values are UTF-8 encoded strings. ICO images can be saved in depth 16, 24, or 32, by using the "depth" parameter. When the ICO saver is given "x_hot" and "y_hot" parameters, it produces a CUR instead of an ICO.

This method raises the GError exception if an error occurs during the save operation.

### gtk.gdk.Pixbuf.save_to_callback

        def save_to_callback(save_func, type, options=None, user_data=None)

`save_func` : | a function that is called to save each block of data that the save routine generates.
`type` : | the name of the file format.
`options` : | a Python dict containing key-value string pairs or `None`
`user_data` : | user-specified data passed to `save_func` or `None`

### Note

This method was available in PyGTK 2.8 and above.

The `save_to_callback`() method saves the pixbuf in the format specified by `type` by feeding the pixbuf data to the callback function specified by `save_func`. `type` may be "jpeg", "png" or "ico" or other installed formats. If `options` is not `None` it should be a Python dict containing key-value string pairs that modify the save parameters. For example:

            pixbuf.save_to_callback(func, "jpeg", {"quality":"100"})

See the `save`() method for more information on formats. If `user_data` is not None it is passed to `save_func` with each invocation.

This method raises a GError exception or exceptions raised by `save_func` if an error occurs during the save operation.

The signature of `save_func` is:

    def pixbuf_save_func(buf, data=None):

where `buf` is a Python string containing the pixbuf data and `data` is `user_data`. `pixbuf_save_func` returns `True` if successful or `False` on failure.

### gtk.gdk.Pixbuf.add_alpha

        def add_alpha(substitute_color, r, g, b)

`substitute_color` : | if `False`, the (`r`, `g`, `b`) arguments will be ignored.
`r` : | the red value to substitute.
`g` : | the green value to substitute.
`b` : | the blue value to substitute.
Returns : | a new `gtk.gdk.Pixbuf`.

The `add_alpha`() method returns a new `gtk.gdk.Pixbuf` created from the pixbuf with an alpha channel added. If the pixbuf already had an alpha channel, the channel values are copied; otherwise, the alpha channel is initialized to 255 (full opacity).

If `substitute_color` is `True`, then the color specified by (`r`, `g`, `b`) will be assigned zero opacity. That is, if you pass (255, 255, 255) for the substitute color, all white pixels will become fully transparent.

### gtk.gdk.Pixbuf.copy_area

        def copy_area(src_x, src_y, width, height, dest_pixbuf, dest_x, dest_y)

`src_x` : | the X coordinate within the pixbuf.
`src_y` : | the Y coordinate within the pixbuf.
`width` : | the width of the area to copy.
`height` : | the height of the area to copy.
`dest_pixbuf` : | the destination pixbuf.
`dest_x` : | the X coordinate within `dest_pixbuf`.
`dest_y` : | the Y coordinate within `dest_pixbuf`.

The `copy_area`() method copies a rectangular area from the pixbuf to the destination `gtk.gdk.Pixbuf` specified by `dest_pixbuf`. Conversion of pixbuf formats is done automatically.

### gtk.gdk.Pixbuf.saturate_and_pixelate

        def saturate_and_pixelate(dest, saturation, pixelate)

`dest` : | the `gtk.gdk.Pixbuf` to write the modified version of the pixbuf
`saturation` : | the saturation factor
`pixelate` : | if `True` pixelate `dest`

The `saturate_and_pixelate`() method modifies the saturation and optionally pixelates the pixbuf, placing the result in `dest`. the pixbuf and `dest` may be the same `gtk.gdk.Pixbuf` with no ill effects. If `saturation` is 1.0 then saturation is not changed. If it's less than 1.0, saturation is reduced (the image is darkened); if greater than 1.0, saturation is increased (the image is brightened). If `pixelate` is `True`, then pixels are faded in a checkerboard pattern to create a pixelated image. The pixbuf and `dest` must have the same image format, size, and rowstride.

### gtk.gdk.Pixbuf.scale

        def scale(dest, dest_x, dest_y, dest_width, dest_height, offset_x, offset_y, scale_x, scale_y, interp_type)

`dest` : | the `gtk.gdk.Pixbuf` the scaling is rendered to.
`dest_x` : | the X coordinate for the rectangle
`dest_y` : | the Y coordinate for the rectangle
`dest_width` : | the width of the rectangle
`dest_height` : | the height of the rectangle
`offset_x` : | the offset in the X direction (currently rounded to an integer)
`offset_y` : | the offset in the Y direction (currently rounded to an integer)
`scale_x` : | the scale factor in the X direction
`scale_y` : | the scale factor in the Y direction
`interp_type` : | the interpolation type for the transformation.

The `scale`() method creates a transformation of the pixbuf's image by scaling by `scale_x` and `scale_y` and translating by `offset_x` and `offset_y` it, then rendering the rectangle (`dest_x`, `dest_y`, `dest_width`, `dest_height`) of the resulting image onto the destination image specified by `dest` replacing the previous contents. The value of `interp_type` must be one of:

`gtk.gdk.INTERP_NEAREST` | Nearest neighbor sampling; this is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be OK when scaling up.
`gtk.gdk.INTERP_TILES` | This is an accurate simulation of the PostScript image operator without any interpolation enabled. Each pixel is rendered as a tiny parallelogram of solid color, the edges of which are implemented with antialiasing. It resembles nearest neighbor for enlargement, and bilinear for reduction.
`gtk.gdk.INTERP_BILINEAR` | Best quality/speed balance; use this mode by default. Bilinear interpolation. For enlargement, it is equivalent to point-sampling the ideal bilinear-interpolated image. For reduction, it is equivalent to laying down small tiles and integrating over the coverage area.
`gtk.gdk.INTERP_HYPER` | This is the slowest and highest quality reconstruction function. It is derived from the hyperbolic filters in Wolberg's "Digital Image Warping", and is formally defined as the hyperbolic-filter sampling the ideal hyperbolic-filter interpolated image (the filter is designed to be idempotent for 1:1 pixel mapping).

Try the `scale_simple`() method as an alternative with a simpler interface.

### gtk.gdk.Pixbuf.composite

        def composite(dest, dest_x, dest_y, dest_width, dest_height, offset_x, offset_y, scale_x, scale_y, interp_type, overall_alpha)

`dest` : | the output `gtk.gdk.Pixbuf`
`dest_x` : | the X coordinate for the rectangle
`dest_y` : | the top coordinate for the rectangle
`dest_width` : | the width of the rectangle
`dest_height` : | the height of the rectangle
`offset_x` : | the offset in the X direction (currently rounded to an integer)
`offset_y` : | the offset in the Y direction (currently rounded to an integer)
`scale_x` : | the scale factor in the X direction
`scale_y` : | the scale factor in the Y direction
`interp_type` : | the interpolation type for the transformation.
`overall_alpha` : | overall alpha for source image (0..255)

The `composite`() method creates a transformation of the pixbuf's image by scaling by `scale_x` and `scale_y` and translating by `offset_x` and `offset_y`, then compositing the rectangle (`dest_x`, `dest_y`, `dest_width`, `dest_height`) of the resulting image onto the destination image. The value of `interp_type` must be one of:

`gtk.gdk.INTERP_NEAREST` | Nearest neighbor sampling; this is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be OK when scaling up.
`gtk.gdk.INTERP_TILES` | This is an accurate simulation of the PostScript image operator without any interpolation enabled. Each pixel is rendered as a tiny parallelogram of solid color, the edges of which are implemented with antialiasing. It resembles nearest neighbor for enlargement, and bilinear for reduction.
`gtk.gdk.INTERP_BILINEAR` | Best quality/speed balance; use this mode by default. Bilinear interpolation. For enlargement, it is equivalent to point-sampling the ideal bilinear-interpolated image. For reduction, it is equivalent to laying down small tiles and integrating over the coverage area.
`gtk.gdk.INTERP_HYPER` | This is the slowest and highest quality reconstruction function. It is derived from the hyperbolic filters in Wolberg's "Digital Image Warping", and is formally defined as the hyperbolic-filter sampling the ideal hyperbolic-filter interpolated image (the filter is designed to be idempotent for 1:1 pixel mapping).

### gtk.gdk.Pixbuf.composite_color

        def composite_color(dest, dest_x, dest_y, dest_width, dest_height, offset_x, offset_y, scale_x, scale_y, interp_type, overall_alpha, check_x, check_y, check_size, color1, color2)

`dest` : | the output `gtk.gdk.Pixbuf`
`dest_x` : | the X coordinate for the rectangle
`dest_y` : | the top coordinate for the rectangle
`dest_width` : | the width of the rectangle
`dest_height` : | the height of the rectangle
`offset_x` : | the offset in the X direction (currently rounded to an integer)
`offset_y` : | the offset in the Y direction (currently rounded to an integer)
`scale_x` : | the scale factor in the X direction
`scale_y` : | the scale factor in the Y direction
`interp_type` : | the interpolation type for the transformation.
`overall_alpha` : | overall alpha for source image (0..255)
`check_x` : | the X offset for the checkboard (origin of checkboard is at -`check_x`, -`check_y`)
`check_y` : | the Y offset for the checkboard
`check_size` : | the size of checks in the checkboard (must be a power of two)
`color1` : | the color of check at upper left
`color2` : | the color of the other check

The `composite_color`() method creates a transformation of the source image `src` by scaling by `scale_x` and `scale_y` and translating by `offset_x` and `offset_y`, then compositing the rectangle (`dest_x` ,`dest_y`, `dest_width`, `dest_height`) of the resulting image with a checkboard of the colors `color1` and `color2` and renders it onto the destination image. The value of `interp_type` must be one of:

`gtk.gdk.INTERP_NEAREST` | Nearest neighbor sampling; this is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be OK when scaling up.
`gtk.gdk.INTERP_TILES` | This is an accurate simulation of the PostScript image operator without any interpolation enabled. Each pixel is rendered as a tiny parallelogram of solid color, the edges of which are implemented with antialiasing. It resembles nearest neighbor for enlargement, and bilinear for reduction.
`gtk.gdk.INTERP_BILINEAR` | Best quality/speed balance; use this mode by default. Bilinear interpolation. For enlargement, it is equivalent to point-sampling the ideal bilinear-interpolated image. For reduction, it is equivalent to laying down small tiles and integrating over the coverage area.
`gtk.gdk.INTERP_HYPER` | This is the slowest and highest quality reconstruction function. It is derived from the hyperbolic filters in Wolberg's "Digital Image Warping", and is formally defined as the hyperbolic-filter sampling the ideal hyperbolic-filter interpolated image (the filter is designed to be idempotent for 1:1 pixel mapping).

See the `composite_color_simple`() method for a simpler variant of this method suitable for most tasks.

### gtk.gdk.Pixbuf.scale_simple

        def scale_simple(dest_width, dest_height, interp_type)

`dest_width` : | the width of destination image
`dest_height` : | the height of destination image
`interp_type` : | the interpolation type for the transformation.
Returns : | the new `gtk.gdk.Pixbuf`, or `None` if not enough memory could be allocated for it.

The `scale_simple`() method returns a new `gtk.gdk.Pixbuf` containing a copy of the pixbuf scaled to `dest_width` x `dest_height`. The pixbuf is unaffected by the scaling operation. The value of `interp_type` must be one of:

`gtk.gdk.INTERP_NEAREST` | Nearest neighbor sampling; this is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be OK when scaling up.
`gtk.gdk.INTERP_TILES` | This is an accurate simulation of the PostScript image operator without any interpolation enabled. Each pixel is rendered as a tiny parallelogram of solid color, the edges of which are implemented with antialiasing. It resembles nearest neighbor for enlargement, and bilinear for reduction.
`gtk.gdk.INTERP_BILINEAR` | Best quality/speed balance; use this mode by default. Bilinear interpolation. For enlargement, it is equivalent to point-sampling the ideal bilinear-interpolated image. For reduction, it is equivalent to laying down small tiles and integrating over the coverage area.
`gtk.gdk.INTERP_HYPER` | This is the slowest and highest quality reconstruction function. It is derived from the hyperbolic filters in Wolberg's "Digital Image Warping", and is formally defined as the hyperbolic-filter sampling the ideal hyperbolic-filter interpolated image (the filter is designed to be idempotent for 1:1 pixel mapping).

`interp_type` should be `gtk.gdk.INTERP_NEAREST` if you want maximum speed (but when scaling down `gtk.gdk.INTERP_NEAREST` is usually unusably ugly). The default `interp_type` should be `GDK_INTERP_BILINEAR` which offers reasonable quality and speed.

You can scale a sub-portion of `src` by creating a sub-pixbuf pointing into `src`; see the `subpixbuf`() method for more information.

For more complicated scaling/compositing see the `scale`() and `composite`() methods.

### gtk.gdk.Pixbuf.composite_color_simple

        def composite_color_simple(dest_width, dest_height, interp_type, overall_alpha, check_size, color1, color2)

`dest_width` : | the width of destination image
`dest_height` : | the height of destination image
`interp_type` : | the interpolation type for the transformation.
`overall_alpha` : | overall alpha for source image (0..255)
`check_size` : | the size of checks in the checkboard (must be a power of two)
`color1` : | the color of check at upper left
`color2` : | the color of the other check
Returns : | the new `gtk.gdk.Pixbuf`, or `NULL` if not enough memory could be allocated for it.

The `composite_color_simple`() method returns a new `gtk.gdk.Pixbuf` by scaling the pixbuf to `dest_width` x `dest_height` and compositing the result with a checkboard of colors `color1` and `color2`. The value of `interp_type` must be one of:

`gtk.gdk.INTERP_NEAREST` | Nearest neighbor sampling; this is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be OK when scaling up.
`gtk.gdk.INTERP_TILES` | This is an accurate simulation of the PostScript image operator without any interpolation enabled. Each pixel is rendered as a tiny parallelogram of solid color, the edges of which are implemented with antialiasing. It resembles nearest neighbor for enlargement, and bilinear for reduction.
`gtk.gdk.INTERP_BILINEAR` | Best quality/speed balance; use this mode by default. Bilinear interpolation. For enlargement, it is equivalent to point-sampling the ideal bilinear-interpolated image. For reduction, it is equivalent to laying down small tiles and integrating over the coverage area.
`gtk.gdk.INTERP_HYPER` | This is the slowest and highest quality reconstruction function. It is derived from the hyperbolic filters in Wolberg's "Digital Image Warping", and is formally defined as the hyperbolic-filter sampling the ideal hyperbolic-filter interpolated image (the filter is designed to be idempotent for 1:1 pixel mapping).

See the `composite_color`() method for a more powerful but complicated interface.

### gtk.gdk.Pixbuf.get_pixels_array

        def get_pixels_array()

Returns : | a Numeric Python array containing the pixel data of the pixbuf

### Note

This method is available in PyGTK 2.2 and above.

The `get_pixels_array`() method returns a Numeric Python array containing the pixel data of the pixbuf.

### Note

PyGTK must be compiled with Numeric Python support for this method to be available.

### gtk.gdk.Pixbuf.subpixbuf

        def subpixbuf(src_x, src_y, width, height)

`src_x` : | X coord in the pixbuf
`src_y` : | Y coord in the pixbuf
`width` : | width of region in the pixbuf
`height` : | height of region in the pixbuf
Returns : | a new `gtk.gdk.Pixbuf`

### Note

This method is available in PyGTK 2.4 and above.

The `subpixbuf`() method creates a new `gtk.gdk.Pixbuf` that represents a sub-region of the pixbuf. The new pixbuf shares its pixels with the original pixbuf, so writing to one affects both.

### gtk.gdk.Pixbuf.rotate_simple

        def rotate_simple(angle)

`angle` : | the rotation angle
Returns : | a new `gtk.gdk.Pixbuf`

### Note

This method is available in PyGTK 2.10 and above.

The `rotate_simple`() method creates a new `gtk.gdk.Pixbuf` by roatating the given pixbuf by a multiple of 90 degrees as specified by `angle` which is one of the GDK Pixbuf Rotation Constants

## Functions

### gtk.gdk.pixbuf_new_from_file

        def gtk.gdk.pixbuf_new_from_file(filename)

`filename` : | the name of the file containing the image to load
Returns : | a new `gtk.gdk.Pixbuf`.

The `gtk.gdk.pixbuf_new_from_file`() function returns a new `gtk.gdk.Pixbuf` containing an image loaded from the file specified by `filename`. The image file format is detected automatically. The application will block until the image is done loading. This method can be used by applications in which blocking is acceptable while an image is being loaded (small images in general). Applications that need progressive loading should use `gtk.gdk.PixbufLoader` instead.

This function raises the GError exception if an error occurs during the loading of the pixbuf.

### gtk.gdk.pixbuf_new_from_file_at_size

        def gtk.gdk.pixbuf_new_from_file_at_size(filename, width, height)

`filename` : | the name of the file containing the image to load
`width` : | The width the image should have
`height` : | The height the image should have
Returns : | a new `gtk.gdk.Pixbuf`.

### Note

This function is available in PyGTK 2.4 and above.

The `gtk.gdk.pixbuf_new_from_file_at_size`() function returns a new `gtk.gdk.Pixbuf` containing an image loaded from the file specified by `filename` with it scaled to the size specified by `width` and `height`. The image file format is detected automatically. The application will block until the image is done loading. This function can be used by applications in which blocking is acceptable while an image is being loaded (small images in general). Applications that need progressive loading should use a `gtk.gdk.PixbufLoader` instead.

This function raises the GError exception if an error occurs during the loading of the pixbuf.

### gtk.gdk.pixbuf_new_from_data

        def gtk.gdk.pixbuf_new_from_data(data, colorspace, has_alpha, bits_per_sample, width, height, rowstride)

`data` : | a string containing image data in 8-bit/sample packed format.
`colorspace` : | the colorspace for the image data.
`has_alpha` : | If `True`, the data has an opacity channel.
`bits_per_sample` : | the number of bits per sample.
`width` : | the width of the image in pixels.
`height` : | the height of the image in pixels.
`rowstride` : | the distance in bytes between row starts.
Returns : | a `gtk.gdk.Pixbuf`

### Note

This function is available in PyGTK 2.2 and above.

The `gtk.gdk.pixbuf_new_from_data`() function returns a new pixbuf created from the string specified by `data`. `data` must be RGB image data with 8 bits per sample. `colorspace` must be `gtk.gdk.COLORSPACE_RGB`.

### gtk.gdk.pixbuf_new_from_array

        def gtk.gdk.pixbuf_new_from_array(array, colorspace, bits_per_sample)

`array` : | a string containing image data in 8-bit/sample packed format.
`colorspace` : | the colorspace for the image data.
`bits_per_sample` : | the number of bits per sample.
Returns : | a `gtk.gdk.Pixbuf`

### Note

This function is available in PyGTK 2.2 and above.

The `gtk.gdk.pixbuf_new_from_array`() function returns a new pixbuf created from the Numeric Python array specified by `array`. `array` must be a 3 or 4 dimensional array (4 if the image has an alpha channel) with `bits_per_sample` bits per sample. `colorspace` must be `gtk.gdk.COLORSPACE_RGB`.

### Note

PyGTK must be compiled with the Numeric Python module to support this function.

### gtk.gdk.pixbuf_new_from_xpm_data

        def gtk.gdk.pixbuf_new_from_xpm_data(data)

`data` : | a list of strings containing the XPM image data
Returns : | a `gtk.gdk.Pixbuf`

The `gtk.gdk.pixbuf_new_from_xpm_data`() function returns a new `gtk.gdk.Pixbuf` by parsing `XPM` data in memory specified by `data`. `data` is a list of strings containing the `XPM` data.

### gtk.gdk.pixbuf_new_from_inline

        def gtk.gdk.pixbuf_new_from_inline(data_length, data, copy_pixels)

`data_length` : | the length in bytes of the `data`
`data` : | a string containing the inline pixbuf data
`copy_pixels` : | if `True` the pixel data should be copied
Returns : | a new `gtk.gdk.Pixbuf` object

The `gtk.gdk.pixbuf_new_from_inline`() function returns a `gtk.gdk.Pixbuf` from a flat representation that is suitable for storing as inline data in a program. This is useful if you want to ship a program with images, but don't want to depend on any external files.

GTK+ ships with a program called gdk-pixbuf-csource which allows for conversion of an image into such a inline representation.In almost all cases, you should pass the `--raw` flag to gdk-pixbuf-csource. A sample invocation would be:

      gdk-pixbuf-csource --raw --name=myimage_inline myimage.png

For the typical case where the inline pixbuf is read-only static data, you don't need to copy the pixel data unless you intend to write to it, so you can pass `False` for `copy_pixels`.

This function raises the GError exception if an error occurs during the loading of the pixbuf.

### gtk.gdk.pixbuf_get_formats

        def gtk.gdk.pixbuf_get_formats()

Returns : | a list of image formats as Python dicts

The `gtk.gdk.pixbuf_get_formats`() function returns a list of the supported image formats as a Python dict. The keys of the image format dict are:

`name` : | the name of the image format.
`description` : | a description of the image format.
`mime_types` : | a list of the mime types this image matches.
`extensions` : | a list of typical filename extensions for the image format.
`is_writable` : | if `True` the image can be written to a file

### gtk.gdk.pixbuf_get_file_info

        def gtk.gdk.pixbuf_get_file_info(filename)

`filename` : | the name of the file to check
Returns : | an image format as a Python dict

The `gtk.gdk.pixbuf_get_file_info`() function reads enough of the file specified by `filename` to determine its image format and then returns the image format information in a Python dict. See the `gtk.gdk.pixbuf_get_formats`() function for more details on the image format dict.

Prev | Up | Next
gtk.gdk.PangoRenderer | Home | gtk.gdk.PixbufAnimation