|Portability||portable (depends on GHC)|
Pixbufs 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
Pixbufs and to scale and crop a
Pixbufand compose the result with an existing image.
Pixbufs can be displayed on screen by either creating an
Imagethat from the
Pixbufor by rendering (part of) the
Pixbufinto a vanilla widget like
- data Pixbuf
- class GObjectClass o => PixbufClass o
- castToPixbuf :: GObjectClass obj => obj -> Pixbuf
- gTypePixbuf :: GType
- toPixbuf :: PixbufClass o => o -> Pixbuf
- data PixbufError
- data Colorspace = ColorspaceRgb
- pixbufNew :: Colorspace -> Bool -> Int -> Int -> Int -> IO Pixbuf
- pixbufNewFromData :: Ptr CUChar -> Colorspace -> Bool -> Int -> 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 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
- 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 :: Pixbuf -> IO Pixbuf
- pixbufFlipVertically :: Pixbuf -> IO Pixbuf
- pixbufRotateSimple :: Pixbuf -> PixbufRotation -> IO Pixbuf
- data PixbufRotation
- 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)
- pixbufRenderThresholdAlpha :: Pixbuf -> Bitmap -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> IO ()
- pixbufRenderPixmapAndMaskForColormap :: Pixbuf -> Colormap -> Int -> IO (Pixmap, Maybe Bitmap)
Error codes for loading image files.
Enumerate all supported color spaces.
- Only RGB is supported right now.
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.
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.
the name of the file
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.
Create a new image from a static pointer.
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
@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
#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
"-#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
pixbufNewFromInline with this pointer will
return the image in the object file. Creating the C file with
--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.
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
pixbufNewFromInlinefor an example.
Create a restricted view of an image.
- This function returns a
Pixbufobject 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.
Create a new image from a String.
- Creates a new pixbuf from a string description.
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.
Query if the image has an alpha channel.
- The alpha channel determines the opaqueness of the pixel.
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.
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 * nChannelsfor the pixel. If the array contains bytes (or
p+0is the red value,
p+3the alpha (transparency) channel if present. If the alpha channel is present, the array can accessed as an array over
Word32to modify a whole pixel at a time. See also
- Calling this function without explicitly giving it a type will often
lead to a compiler error since the type parameter
eis 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
unsafeWritewhich have the same type signatures as
writeArray. Note that these are internal functions that might change with GHC.
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.
Returns an attribut of an image.
- Looks up if some information was stored under the
keywhen this image was saved.
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.
catchGErrorJustand one of the error codes in
How an image is scaled.
- 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.
- 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.
- 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.
- 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).
|-> IO Pixbuf|
Scale an image.
- Creates a new
Pixbufcontaining a copy of
srcscaled to the given measures. Leaves
interpaffects the quality and speed of the scaling function.
InterpNearestis the fastest option but yields very poor quality when scaling down.
InterpBilinearis a good trade-off between speed and quality and should thus be used as a default.
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
scaleYand translate the image by
offsetY. Whatever is in the intersection with the rectangle
destHeightwill be rendered into
- The rectangle in the destination is simply overwritten. Use
pixbufCompositeif you need to blend the source image onto the destination.
the interpolation type for the transformation.
|-> IO ()|
Blend a scaled image part onto another image.
Flips a pixbuf horizontally and returns the result in a new pixbuf.
Flips a pixbuf vertically and returns the result in a new pixbuf.
Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf.
The possible rotations which can be passed to
To make them easier to use, their numerical values are the actual degrees.
Add an opacity layer to the
Source X coordinate within the source pixbuf
Source Y coordinate within the source pixbuf
Width of the area to copy
Height of the area to copy
X coordinate within the destination pixbuf
Y coordinate within the destination pixbuf
|-> IO ()|
Take a screenshot of a
- This function creates a
Pixbufand 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
Pixbufwith no alpha channel containing the part of the
Drawablespecified by the rectangle. The function will return
Nothingif the window is not currently visible.
Removed in Gtk3.
Bitmap where the bilevel mask will be painted to.
Source X coordinate.
source Y coordinate.
Destination X coordinate.
Destination Y coordinate.
Width of region to threshold, or -1 to use pixbuf width
Height of region to threshold, or -1 to use pixbuf height
Opacity values below this will be painted as zero; all other values will be painted as one.
|-> IO ()|
Takes the opacity values in a rectangular portion of a pixbuf and thresholds them to produce a bi-level alpha mask that can be used as a clipping mask for a drawable.
Removed in Gtk3.
Threshold value for opacity values
|-> IO (Pixmap, Maybe Bitmap)|
(Created pixmap, created mask)
Creates a pixmap and a mask bitmap which are returned and renders
a pixbuf and its corresponding thresholded alpha mask to them. This
is merely a convenience function; applications that need to render
pixbufs with dither offsets or to given drawables should use
The pixmap that is created uses the
Colormap specified by
colormap. This colormap must match the colormap of the window where
the pixmap will eventually be used or an error will result.
If the pixbuf does not have an alpha channel, then the returned
mask will be
Removed in Gtk3.