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 Pixbuf and
compose the result with an existing image.

Pixbufs 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.

Constructors

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, 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.

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:

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.

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 Word8s), 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 unsafeRead and
unsafeWrite which have the same type signatures
as readArray and writeArray.
Note that these are internal
functions that might change with GHC.

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.

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).

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.

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.

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.

This function returns a copy of the given srcPixbuf, leaving src unmodified.
The new Pixbuf has an alpha (opacity)
channel which defaults to 255 (fully opaque pixels)
unless src already had an alpha channel in which case
the original values are kept.
Passing in a color triple (r,g,b) makes all
pixels that have this color fully transparent
(opacity of 0). The pixel color itself remains unchanged
during this substitution.

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.

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
Graphics.UI.Gtk.Gdk.Drawable.drawPixbuf, and
pixbufRenderThresholdAlpha.

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 Nothing.