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                   (GdkDrawable *drawable,
                                             gint x,
                                             gint y,
                                             gint width,
                                             gint height);
GdkImage*   gdk_image_ref                   (GdkImage *image);
void        gdk_image_unref                 (GdkImage *image);
#define     gdk_image_destroy
GdkColormap* gdk_image_get_colormap         (GdkImage *image);
void        gdk_image_set_colormap          (GdkImage *image,
                                             GdkColormap *colormap);

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

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
{
  GObject parent_instance;
  
  GdkImageType	type;
  GdkVisual    *visual;	    /* visual used to create the image */
  GdkByteOrder	byte_order;
  gint		width;
  gint		height;
  guint16	depth;
  guint16	bpp;	        /* bytes per pixel */
  guint16	bpl;	        /* bytes per line */
  guint16       bits_per_pixel; /* bits per pixel */
  gpointer	mem;

  GdkColormap  *colormap;
  
  gpointer windowing_data;
};

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


gdk_image_new ()

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

Creates a new GdkImage.


enum GdkImageType

typedef enum
{
  GDK_IMAGE_NORMAL,
  GDK_IMAGE_SHARED,
  GDK_IMAGE_FASTEST
} GdkImageType;

Specifies the type of a GdkImage.


gdk_image_new_bitmap ()

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

Warning

gdk_image_new_bitmap is deprecated and should not be used in newly-written code.

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

Warning

THIS FUNCTION IS INCREDIBLY BROKEN. The passed-in data must be allocated by malloc() (NOT g_malloc()) and will be freed when the image is freed.


gdk_image_get ()

GdkImage*   gdk_image_get                   (GdkDrawable *drawable,
                                             gint x,
                                             gint y,
                                             gint width,
                                             gint height);

Warning

gdk_image_get is deprecated and should not be used in newly-written code.

This is a deprecated wrapper for gdk_drawable_get_image(); gdk_drawable_get_image() should be used instead. Or even better: in most cases gdk_pixbuf_get_from_drawable() is the most convenient choice.

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


gdk_image_ref ()

GdkImage*   gdk_image_ref                   (GdkImage *image);

Warning

gdk_image_ref is deprecated and should not be used in newly-written code.

Deprecated function; use g_object_ref() instead.


gdk_image_unref ()

void        gdk_image_unref                 (GdkImage *image);

Warning

gdk_image_unref is deprecated and should not be used in newly-written code.

Deprecated function; use g_object_unref() instead.


gdk_image_destroy

#define gdk_image_destroy              gdk_image_unref

Warning

gdk_image_destroy is deprecated and should not be used in newly-written code.

Destroys a GdkImage, freeing any resources allocated for it.


gdk_image_get_colormap ()

GdkColormap* gdk_image_get_colormap         (GdkImage *image);

Retrieves the colormap for a given image, if it exists. An image will have a colormap if the drawable from which it was created has a colormap, or if a colormap was set explicitely with gdk_image_set_colormap().


gdk_image_set_colormap ()

void        gdk_image_set_colormap          (GdkImage *image,
                                             GdkColormap *colormap);

Sets the colormap for the image to the given colormap. Normally there's no need to use this function, images are created with the correct colormap if you get the image from a drawable. If you create the image from scratch, use the colormap of the drawable you intend to render the image to.


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.


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.

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.