GDK Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Images

## Name

Images -- an area for bit-mapped graphics stored on the X Windows client.

## Synopsis

    #include <gdk/gdk.h>

    struct      GdkImage;
    GdkImage*   gdk_image_new                   (GdkImageType type,
                                                 GdkVisual *visual,
                                                 gint width,
                                                 gint height);
    enum        GdkImageType;
    GdkImage*   gdk_image_new_bitmap            (GdkVisual *visual,
                                                 gpointer data,
                                                 gint width,
                                                 gint height);
    GdkImage*   gdk_image_get                   (GdkWindow *window,
                                                 gint x,
                                                 gint y,
                                                 gint width,
                                                 gint height);
    void        gdk_image_destroy               (GdkImage *image);

    void        gdk_image_put_pixel             (GdkImage *image,
                                                 gint x,
                                                 gint y,
                                                 guint32 pixel);
    guint32     gdk_image_get_pixel             (GdkImage *image,
                                                 gint x,
                                                 gint y);

## Description

The GdkImage type represents an area for drawing graphics. It has now been superceded to a large extent by the much more flexible GdkRGB functions.

To create an empty GdkImage use gdk_image_new(). To create a GdkImage from bitmap data use gdk_image_new_bitmap(). To create an image from part of a GdkWindow use gdk_image_get().

The image can be manipulated with gdk_image_get_pixel() and gdk_image_put_pixel(), or alternatively by changing the actual pixel data. Though manipulating the pixel data requires complicated code to cope with the different formats that may be used.

To draw a GdkImage in a GdkWindow or GdkPixmap use gdk_draw_image().

To destroy a GdkImage use gdk_image_destroy().

## Details

### struct GdkImage

    struct GdkImage
    {
      GdkImageType	type;
      GdkVisual    *visual;	    /* visual used to create the image */
      GdkByteOrder	byte_order;
      guint16	width;
      guint16	height;
      guint16	depth;
      guint16	bpp;	    /* bytes per pixel */
      guint16	bpl;	    /* bytes per line */
      gpointer	mem;
    };

The GdkImage struct contains information on the image and the pixel data.

GdkImageType `type` | the type of the image.
GdkVisual *`visual` | the visual.
GdkByteOrder `byte_order` | the byte order.
guint16 `width` | the width of the image in pixels.
guint16 `height` | the height of the image in pixels.
guint16 `depth` | the depth of the image, i.e. the number of bits per pixel.
guint16 `bpp` | the number of bytes per pixel.
guint16 `bpl` | the number of bytes per line of the image.
gpointer `mem` | the pixel data.

### gdk_image_new ()

    GdkImage*   gdk_image_new                   (GdkImageType type,
                                                 GdkVisual *visual,
                                                 gint width,
                                                 gint height);

Creates a new GdkImage.

`type` : | the type of the GdkImage, one of `GDK_IMAGE_NORMAL`, `GDK_IMAGE_SHARED` and `GDK_IMAGE_FASTEST`. `GDK_IMAGE_FASTEST` is probably the best choice, since it will try creating a `GDK_IMAGE_SHARED` image first and if that fails it will then use `GDK_IMAGE_NORMAL`.
`visual` : | the GdkVisual to use for the image.
`width` : | the width of the image in pixels.
`height` : | the height of the image in pixels.
Returns : | a new GdkImage, or NULL if the image could not be created.

### enum GdkImageType

    typedef enum
    {
      GDK_IMAGE_NORMAL,
      GDK_IMAGE_SHARED,
      GDK_IMAGE_FASTEST
    } GdkImageType;

Specifies the type of a GdkImage.

`GDK_IMAGE_NORMAL` | The original X image type, which is quite slow since the image has to be transferred from the client to the server to display it.
`GDK_IMAGE_SHARED` | A faster image type, which uses shared memory to transfer the image data between client and server. However this will only be available if client and server are on the same machine and the shared memory extension is supported by the server.
`GDK_IMAGE_FASTEST` | Specifies that `GDK_IMAGE_SHARED` should be tried first, and if that fails then `GDK_IMAGE_NORMAL` will be used.

### gdk_image_new_bitmap ()

    GdkImage*   gdk_image_new_bitmap            (GdkVisual *visual,
                                                 gpointer data,
                                                 gint width,
                                                 gint height);

Creates a new GdkImage with a depth of 1 from the given data.

`visual` : | the GdkVisual to use for the image.
`data` : | the pixel data.
`width` : | the width of the image in pixels.
`height` : | the height of the image in pixels.
Returns : | a new GdkImage.

### gdk_image_get ()

    GdkImage*   gdk_image_get                   (GdkWindow *window,
                                                 gint x,
                                                 gint y,
                                                 gint width,
                                                 gint height);

Gets part of a GdkWindow and stores it in a new GdkImage.

`window` : | the GdkWindow to copy from.
`x` : | the left edge of the rectangle to copy from `window`.
`y` : | the top edge of the rectangle to copy from `window`.
`width` : | the width of the area to copy, in pixels.
`height` : | the height of the area to copy, in pixels.
Returns : | a new GdkImage with a copy of the given area of `window`.

### gdk_image_destroy ()

    void        gdk_image_destroy               (GdkImage *image);

Destroys a GdkImage, freeing any resources allocated for it.

`image` : | a GdkImage.

### gdk_image_put_pixel ()

    void        gdk_image_put_pixel             (GdkImage *image,
                                                 gint x,
                                                 gint y,
                                                 guint32 pixel);

Sets a pixel in a GdkImage to a given pixel value.

`image` : | a GdkImage.
`x` : | the x coordinate of the pixel to set.
`y` : | the y coordinate of the pixel to set.
`pixel` : | the pixel value to set.

### gdk_image_get_pixel ()

    guint32     gdk_image_get_pixel             (GdkImage *image,
                                                 gint x,
                                                 gint y);

Gets a pixel value at a specified position in a GdkImage.

`image` : | a GdkImage.
`x` : | the x coordinate of the pixel to get.
`y` : | the y coordinate of the pixel to get.
Returns : | the pixel value at the given position.

## See Also

Bitmaps and Pixmaps

  Graphics which are stored on the X Windows server. Since these are stored on the server they can be drawn very quickly, and all of the Drawing Primitives can be used to draw on them. Their main disadvantage is that manipulating individual pixels can be very slow.

GdkRGB

  Built on top of GdkImage, this provides much more functionality, including the dithering of colors to produce better output on low-color displays.

<<< Previous Page | Home | Up | Next Page >>>
GdkRGB | Colormaps and Colors