| Gtk2Hs | Contents | Index

Graphics.UI.Gtk.Gdk.Pixbuf

Portability | portable (depends on GHC)
Stability | provisional
Maintainer | gtk2hs-users@lists.sourceforge.net

Contents

Class Hierarchy
Types
Constructors
Methods

Description

`Pixbuf`s are bitmap images in memory.

- A Pixbuf is used to represent images. It contains information about the image's pixel data, its color space, bits per sample, width and height, and the rowstride or number of bytes between rows.
- This module contains functions to scale and crop `Pixbuf`s and to scale and crop a `Pixbuf` and compose the result with an existing image.
- `Pixbuf`s can be displayed on screen by either creating an `Image` that from the `Pixbuf` or by rendering (part of) the `Pixbuf` into a vanilla widget like `DrawWindow` using Graphics.UI.Gtk.Gdk.Drawable.drawPixbuf.

Synopsis

data Pixbuf
class GObjectClass o => PixbufClass o
castToPixbuf :: GObjectClass obj => obj -> Pixbuf
toPixbuf :: PixbufClass o => o -> Pixbuf

data PixbufError

= PixbufErrorCorruptImage
| PixbufErrorInsufficientMemory
| PixbufErrorBadOption
| PixbufErrorUnknownType
| PixbufErrorUnsupportedOperation
| PixbufErrorFailed

data Colorspace = ColorspaceRgb
pixbufNew :: Colorspace -> Bool -> Int -> Int -> Int -> IO Pixbuf
pixbufNewFromFile :: FilePath -> IO Pixbuf
pixbufNewFromFileAtSize :: String -> Int -> Int -> IO Pixbuf
pixbufNewFromFileAtScale :: String -> Int -> Int -> Bool -> IO Pixbuf
pixbufNewFromInline :: Ptr InlineImage -> IO Pixbuf
data InlineImage
pixbufNewSubpixbuf :: Pixbuf -> Int -> Int -> Int -> Int -> IO Pixbuf
pixbufNewFromXPMData :: [String] -> IO Pixbuf
pixbufGetColorSpace :: Pixbuf -> IO Colorspace
pixbufGetNChannels :: Pixbuf -> IO Int
pixbufGetHasAlpha :: Pixbuf -> IO Bool
pixbufGetBitsPerSample :: Pixbuf -> IO Int
data Ix i => PixbufData i e
pixbufGetPixels :: Storable e => Pixbuf -> IO (PixbufData Int e)
pixbufGetWidth :: Pixbuf -> IO Int
pixbufGetHeight :: Pixbuf -> IO Int
pixbufGetRowstride :: Pixbuf -> IO Int
pixbufGetOption :: Pixbuf -> String -> IO (Maybe String)
type ImageFormat = String
pixbufGetFormats :: [ImageFormat]
pixbufSave :: Pixbuf -> FilePath -> ImageFormat -> [(String, String)] -> IO ()
pixbufCopy :: Pixbuf -> IO Pixbuf

data InterpType

= InterpNearest
| InterpTiles
| InterpBilinear
| InterpHyper

pixbufScaleSimple :: Pixbuf -> Int -> Int -> InterpType -> IO Pixbuf
pixbufScale :: Pixbuf -> Pixbuf -> Int -> Int -> Int -> Int -> Double -> Double -> Double -> Double -> InterpType -> IO ()
pixbufComposite :: Pixbuf -> Pixbuf -> Int -> Int -> Int -> Int -> Double -> Double -> Double -> Double -> InterpType -> Word8 -> IO ()
pixbufFlipHorizontally :: Pixbuf -> IO Pixbuf
pixbufFlipHorazontally
pixbufFlipVertically :: Pixbuf -> IO Pixbuf
pixbufRotateSimple :: Pixbuf -> PixbufRotation -> IO Pixbuf

data PixbufRotation

= PixbufRotateNone
| PixbufRotateCounterclockwise
| PixbufRotateUpsidedown
| PixbufRotateClockwise

pixbufAddAlpha :: Pixbuf -> Maybe (Word8, Word8, Word8) -> IO Pixbuf
pixbufCopyArea :: Pixbuf -> Int -> Int -> Int -> Int -> Pixbuf -> Int -> Int -> IO ()
pixbufFill :: Pixbuf -> Word8 -> Word8 -> Word8 -> Word8 -> IO ()
pixbufGetFromDrawable :: DrawableClass d => d -> Rectangle -> IO (Maybe Pixbuf)

Class Hierarchy

     |  GObject
     |   +----Pixbuf

Types
data Pixbuf

Instances

GObjectClass Pixbuf
PixbufClass Pixbuf

class GObjectClass o => PixbufClass o

Instances

PixbufClass Pixbuf

castToPixbuf :: GObjectClass obj => obj -> Pixbuf
toPixbuf :: PixbufClass o => o -> Pixbuf
data PixbufError

Error codes for loading image files.
Constructors

PixbufErrorCorruptImage |
PixbufErrorInsufficientMemory |
PixbufErrorBadOption |
PixbufErrorUnknownType |
PixbufErrorUnsupportedOperation |
PixbufErrorFailed |

Instances

Enum PixbufError
GErrorClass PixbufError

data Colorspace

Enumerate all supported color spaces.

- Only RGB is supported right now.

Constructors

ColorspaceRgb |

Instances

Enum Colorspace

Constructors
pixbufNew :: Colorspace -> Bool -> Int -> Int -> Int -> IO Pixbuf

Create a new image in memory.

- Creates a new pixbuf structure and allocates a buffer for it. Note that the buffer is not cleared initially.
- The boolean flag is true if the pixbuf should have an alpha (transparency) channel. The next integer denotes the bits per color sample, e.g. 8 bits per color for 2^24 colors. The last two integers denote the width and height, respectively.

pixbufNewFromFile :: FilePath -> IO Pixbuf

Load an image synchonously.

- Use this function to load only small images as this call will block.
- If an error occurs, the function will throw an exception that can be caught using e.g. System.Glib.GError.catchGErrorJust and one of the error codes in `PixbufError`.

pixbufNewFromFileAtSize :: String -> Int -> Int -> IO Pixbuf

Creates a new pixbuf by loading an image from a file. The file format is detected automatically. The image will be scaled to fit in the requested size, preserving the image's aspect ratio.

- If an error occurs, the function will throw an exception that can be caught using e.g. System.Glib.GError.catchGErrorJust and one of the error codes in `PixbufError`.
- Available since Gtk+ version 2.4

pixbufNewFromFileAtScale

:: String | the name of the file
-> Int | target width
-> Int | target height
-> Bool | whether to preserve the aspect ratio
-> IO Pixbuf |

Creates a new pixbuf by loading an image from a file. The file format is detected automatically. The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio.

When preserving the aspect ratio, a width of -1 will cause the image to be scaled to the exact given height, and a height of -1 will cause the image to be scaled to the exact given width. When not preserving aspect ratio, a width or height of -1 means to not scale the image at all in that dimension. Negative values for width and height are allowed since Gtk+ 2.8.

- If an error occurs, the function will throw an exception that can be caught using e.g. System.Glib.GError.catchGErrorJust and one of the error codes in `PixbufError`.
- Available since Gtk+ version 2.6

pixbufNewFromInline :: Ptr InlineImage -> IO Pixbuf

Create a new image from a static pointer.

- Like `pixbufNewFromXPMData`, this function allows to include images in the final binary program. The method used by this function uses a binary representation and therefore needs less space in the final executable. Save the image you want to include as `png` and run:

     @echo #include "my_image.h" > my_image.c
     gdk-pixbuf-csource --raw --extern --name=my_image myimage.png >> my_image.c

on it. Write a header file `my_image.h` containing:

     #include <gdk/gdk.h>
     extern guint8 my_image[];

and save it in the current directory. The created file can be compiled with:

     cc -c my_image.c `pkg-config --cflags gdk-2.0`

into an object file which must be linked into your Haskell program by specifying `my_image.o` and `"-#include my_image.h"` on the command line of GHC. Within you application you delcare a pointer to this image:

     foreign label "my_image" myImage :: Ptr InlineImage

Calling `pixbufNewFromInline` with this pointer will return the image in the object file. Creating the C file with the `--raw` flag will result in a non-compressed image in the object file. The advantage is that the picture will not be copied when this function is called.

data InlineImage

A dymmy type for inline picture data.

- This dummy type is used to declare pointers to image data that is embedded in the executable. See `pixbufNewFromInline` for an example.

pixbufNewSubpixbuf :: Pixbuf -> Int -> Int -> Int -> Int -> IO Pixbuf

Create a restricted view of an image.

- This function returns a `Pixbuf` object which shares the image of the original one but only shows a part of it. Modifying either buffer will affect the other.
- This function throw an exception if the requested bounds are invalid.

pixbufNewFromXPMData :: [String] -> IO Pixbuf

Create a new image from a String.

- Creates a new pixbuf from a string description.

Methods
pixbufGetColorSpace :: Pixbuf -> IO Colorspace
Queries the color space of a pixbuf.
pixbufGetNChannels :: Pixbuf -> IO Int

Queries the number of colors for each pixel.

- This function returns 3 for an RGB image without alpha (transparency) channel, 4 for an RGB image with alpha channel.

pixbufGetHasAlpha :: Pixbuf -> IO Bool

Query if the image has an alpha channel.

- The alpha channel determines the opaqueness of the pixel.

pixbufGetBitsPerSample :: Pixbuf -> IO Int

Queries the number of bits for each color.

- Each pixel is has a number of cannels for each pixel, each channel has this many bits.

data Ix i => PixbufData i e

An array that stored the raw pixel data of a `Pixbuf`.

- See Graphics.UI.Gtk.Gdk.Pixbuf.pixbufGetPixels.

Instances

Storable e => MArray PixbufData e IO

pixbufGetPixels :: Storable e => Pixbuf -> IO (PixbufData Int e)

Retrieve the internal array of raw image data.

- Image data in a pixbuf is stored in memory in uncompressed, packed format. Rows in the image are stored top to bottom, and in each row pixels are stored from left to right. There may be padding at the end of a row. The rowstride value of a pixbuf, as returned by `pixbufGetRowstride`, indicates the number of bytes between rows.
- The returned array is a flat representation of a three dimensional array: x-coordiante, y-coordinate and several channels for each color. The number of channels is usually 3 for plain RGB data or 4 for RGB data with an alpha channel. To read or write a specific pixel use the formula: `p = y * rowstride + x * nChannels` for the pixel. If the array contains bytes (or `Word8`s), `p+0` is the red value, `p+1` green, `p+2` blue and `p+3` the alpha (transparency) channel if present. If the alpha channel is present, the array can accessed as an array over `Word32` to modify a whole pixel at a time. See also `pixbufGetBitsPerSample` and `pixbufGetNChannels`.
- Calling this function without explicitly giving it a type will often lead to a compiler error since the type parameter `e` is underspecified. If this happens the function can be explicitly typed: `pbData <- (pixbufGetPixels pb :: IO (PixbufData Int Word8))`
- If modifying an image through Haskell's array interface is not fast enough, it is possible to use Data.Array.Base.unsafeRead and Data.Array.Base.unsafeWrite which have the same type signatures as Data.Array.MArray.readArray and Data.Array.MArray.writeArray. Note that these are internal functions that might change with GHC.

pixbufGetWidth :: Pixbuf -> IO Int
Queries the width of this image.
pixbufGetHeight :: Pixbuf -> IO Int
Queries the height of this image.
pixbufGetRowstride :: Pixbuf -> IO Int

Queries the rowstride of this image.

- Queries the rowstride of a pixbuf, which is the number of bytes between rows. Use this value to caculate the offset to a certain row.

pixbufGetOption :: Pixbuf -> String -> IO (Maybe String)

Returns an attribut of an image.

- Looks up if some information was stored under the `key` when this image was saved.

type ImageFormat = String
A string representing an image file format.
pixbufGetFormats :: [ImageFormat]
pixbufSave :: Pixbuf -> FilePath -> ImageFormat -> [(String, String)] -> IO ()

Save an image to disk.

- The function takes a list of key - value pairs to specify either how an image is saved or to actually save this additional data with the image. 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. The values are Unicode strings.
- If an error occurs, the function will throw an exception that can be caught using e.g. System.Glib.GError.catchGErrorJust and one of the error codes in `PixbufError`.

pixbufCopy :: Pixbuf -> IO Pixbuf
Create a deep copy of an image.
data InterpType

How an image is scaled.

`InterpNearest`
  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.
`InterpTiles`
  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.
`InterpBilinear`
  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.
`InterpHyper`
  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).

Constructors

InterpNearest |
InterpTiles |
InterpBilinear |
InterpHyper |

Instances

Enum InterpType

pixbufScaleSimple

:: Pixbuf | `src` - the source image
-> Int | `width` - the target width
-> Int | `height` the target height
-> InterpType | interpolation type
-> IO Pixbuf |

Scale an image.

- Creates a new `Pixbuf` containing a copy of `src` scaled to the given measures. Leaves `src` unaffected.
- `interp` affects the quality and speed of the scaling function. `InterpNearest` is the fastest option but yields very poor quality when scaling down. `InterpBilinear` is a good trade-off between speed and quality and should thus be used as a default.

pixbufScale

:: Pixbuf | `src` - the source pixbuf
-> Pixbuf | `dest` - the pixbuf into which to render the results
-> Int | `destX` - the left coordinate for region to render
-> Int | `destY` - the top coordinate for region to render
-> Int | `destWidth` - the width of the region to render
-> Int | `destHeight` - the height of the region to render
-> Double | `offsetX` - the offset in the X direction (currently rounded to an integer)
-> Double | `offsetY` - the offset in the Y direction (currently rounded to an integer)
-> Double | `scaleX` - the scale factor in the X direction
-> Double | `scaleY` - the scale factor in the Y direction
-> InterpType | the interpolation type for the transformation.
-> IO () |

Copy a scaled image part to another image.

- This function is the generic version of `pixbufScaleSimple`. It scales `src` by `scaleX` and `scaleY` and translate the image by `offsetX` and `offsetY`. Whatever is in the intersection with the rectangle `destX`, `destY`, `destWidth`, `destHeight` will be rendered into `dest`.
- The rectangle in the destination is simply overwritten. Use `pixbufComposite` if you need to blend the source image onto the destination.

pixbufComposite

:: Pixbuf | `src` - the source pixbuf
-> Pixbuf | `dest` - the pixbuf into which to render the results
-> Int | `destX` - the left coordinate for region to render
-> Int | `destY` - the top coordinate for region to render
-> Int | `destWidth` - the width of the region to render
-> Int | `destHeight` - the height of the region to render
-> Double | `offsetX` - the offset in the X direction (currently rounded to an integer)
-> Double | `offsetY` - the offset in the Y direction (currently rounded to an integer)
-> Double | `scaleX` - the scale factor in the X direction
-> Double | `scaleY` - the scale factor in the Y direction
-> InterpType | the interpolation type for the transformation.
-> Word8 | `alpha` - the transparency
-> IO () |

Blend a scaled image part onto another image.

- This function is similar to `pixbufScale` but allows the original image to "shine through". The `alpha` value determines how opaque the source image is. Passing `0` is equivalent to not calling this function at all, passing `255` has the same effect as calling `pixbufScale`.

pixbufFlipHorizontally :: Pixbuf -> IO Pixbuf
Flips a pixbuf horizontally and returns the result in a new pixbuf.
pixbufFlipHorazontally
pixbufFlipVertically :: Pixbuf -> IO Pixbuf
Flips a pixbuf vertically and returns the result in a new pixbuf.
pixbufRotateSimple :: Pixbuf -> PixbufRotation -> IO Pixbuf
Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf.
data PixbufRotation

The possible rotations which can be passed to `pixbufRotateSimple`. To make them easier to use, their numerical values are the actual degrees.
Constructors

PixbufRotateNone |
PixbufRotateCounterclockwise |
PixbufRotateUpsidedown |
PixbufRotateClockwise |

Instances

Enum PixbufRotation

pixbufAddAlpha :: Pixbuf -> Maybe (Word8, Word8, Word8) -> IO Pixbuf
pixbufCopyArea

:: Pixbuf | Source pixbuf
-> Int | Source X coordinate within the source pixbuf
-> Int | Source Y coordinate within the source pixbuf
-> Int | Width of the area to copy
-> Int | Height of the area to copy
-> Pixbuf | Destination pixbuf
-> Int | X coordinate within the destination pixbuf
-> Int | Y coordinate within the destination pixbuf
-> IO () |
Copy a rectangular portion into another `Pixbuf`. The source `Pixbuf` remains unchanged. Converion between different formats is done automatically.

pixbufFill :: Pixbuf -> Word8 -> Word8 -> Word8 -> Word8 -> IO ()

Fills a `Pixbuf` with a color.

- The passed-in color is a quadruple consisting of the red, green, blue and alpha component of the pixel. If the `Pixbuf` does not have an alpha channel, the alpha value is ignored.

pixbufGetFromDrawable :: DrawableClass d => d -> Rectangle -> IO (Maybe Pixbuf)

Take a screenshot of a `Drawable`.

- This function creates a `Pixbuf` and fills it with the image currently in the `Drawable` (which might be invalid if the window is obscured or minimized). Note that this transfers data from the server to the client on X Windows.
- This function will return a `Pixbuf` with no alpha channel containing the part of the `Drawable` specified by the rectangle. The function will return `Nothing` if the window is not currently visible.

Produced by Haddock version 2.4.2