Bitmaps and Pixmaps: GDK 2 Reference Manual

Bitmaps and Pixmaps

Bitmaps and Pixmaps — Offscreen drawables

Functions

GdkPixmap *	gdk_pixmap_new ()
GdkBitmap *	gdk_bitmap_create_from_data ()
GdkPixmap *	gdk_pixmap_create_from_data ()
GdkPixmap *	gdk_pixmap_create_from_xpm ()
GdkPixmap *	gdk_pixmap_colormap_create_from_xpm ()
GdkPixmap *	gdk_pixmap_create_from_xpm_d ()
GdkPixmap *	gdk_pixmap_colormap_create_from_xpm_d ()
void	gdk_pixmap_get_size ()

Types and Values

typedef	GdkPixmap
#define	gdk_pixmap_ref
#define	gdk_pixmap_unref
typedef	GdkBitmap
#define	gdk_bitmap_ref
#define	gdk_bitmap_unref

Object Hierarchy

    GObject
    ╰── GdkDrawable
        ╰── GdkPixmap

Includes

#include <gdk/gdk.h>

Description

Pixmaps are offscreen drawables. They can be drawn upon with the standard drawing primitives, then copied to another drawable (such as a GdkWindow) with gdk_pixmap_draw(). The depth of a pixmap is the number of bits per pixels. Bitmaps are simply pixmaps with a depth of 1. (That is, they are monochrome bitmaps - each pixel can be either on or off).

GTK 3 will remove GdkPixmap and GdkBitmap. You should use cairo surfaces instead. However, because a lot of functions still use these types, they are not deprecated.

Functions

gdk_pixmap_new ()

GdkPixmap *
gdk_pixmap_new (GdkDrawable *drawable,
                gint width,
                gint height,
                gint depth);

Create a new pixmap with a given size and depth.

Please use gdk_window_create_similar_surface() instead of this function if you're not forced to use a GdkPixmap. It is intended as the replacement function for this function in GTK 3.

Parameters

drawable	A GdkDrawable, used to determine default values for the new pixmap. Can be `NULL` if `depth` is specified,
width	The width of the new pixmap in pixels.
height	The height of the new pixmap in pixels.
depth	The depth (number of bits per pixel) of the new pixmap. If -1, and `drawable` is not `NULL`, the depth of the new pixmap will be equal to that of `drawable` .

Returns

the GdkPixmap

gdk_bitmap_create_from_data ()

GdkBitmap *
gdk_bitmap_create_from_data (GdkDrawable *drawable,
                             const gchar *data,
                             gint width,
                             gint height);

gdk_bitmap_create_from_data has been deprecated since version 2.22 and should not be used in newly-written code.

You can create a Cairo image surface using cairo_image_surface_create_for_data() instead. Specify CAIRO_FORMAT_A1 as the format to get a bitmap. Keep in mind that Cairo images must have a rowstride of 4 bytes, so you will need to align your data properly. If you must use a pixmap, use gdk_pixmap_new() with a depth of 1 to create a bitmap and then use gdk_cairo_create(), cairo_set_source_surface() and cairo_paint() to draw the image surface to the bitmap.

Creates a new bitmap from data in XBM format.

Parameters

drawable	a GdkDrawable, used to determine default values for the new pixmap. Can be `NULL`, in which case the root window is used.
data	a pointer to the XBM data.
width	the width of the new pixmap in pixels.
height	the height of the new pixmap in pixels.

Returns

the GdkBitmap

gdk_pixmap_create_from_data ()

GdkPixmap *
gdk_pixmap_create_from_data (GdkDrawable *drawable,
                             const gchar *data,
                             gint width,
                             gint height,
                             gint depth,
                             const GdkColor *fg,
                             const GdkColor *bg);

gdk_pixmap_create_from_data has been deprecated since version 2.22 and should not be used in newly-written code.

If you must replicate the functionality of this function, create a pixmap using gdk_pixmap_new(), cairo_paint() it with the background color and then create a Cairo image surface as pointed out in the docs to gdk_bitmap_create_from_data() and use this surface with cairo_mask_surface() to paint the foreground color.

Create a two-color pixmap from data in XBM data.

Parameters

drawable	a GdkDrawable, used to determine default values for the new pixmap. Can be `NULL`, if the depth is given.
data	a pointer to the data.
width	the width of the new pixmap in pixels.
height	the height of the new pixmap in pixels.
depth	the depth (number of bits per pixel) of the new pixmap.
fg	the foreground color.
bg	the background color.

Returns

the GdkPixmap

gdk_pixmap_create_from_xpm ()

GdkPixmap *
gdk_pixmap_create_from_xpm (GdkDrawable *drawable,
                            GdkBitmap **mask,
                            const GdkColor *transparent_color,
                            const gchar *filename);

gdk_pixmap_create_from_xpm has been deprecated since version 2.22 and should not be used in newly-written code.

Use a GdkPixbuf instead. You can use gdk_pixbuf_new_from_file() to create it. If you must use a pixmap, use gdk_pixmap_new() to create it and Cairo to draw the pixbuf onto it.

Create a pixmap from a XPM file.

Parameters

drawable	a GdkDrawable, used to determine default values for the new pixmap.
mask	(out) a pointer to a place to store a bitmap representing the transparency mask of the XPM file. Can be `NULL`, in which case transparency will be ignored.
transparent_color	the color to be used for the pixels that are transparent in the input file. Can be `NULL`, in which case a default color will be used.
filename	the filename of a file containing XPM data.

Returns

the GdkPixmap.

[transfer none]

gdk_pixmap_colormap_create_from_xpm ()

GdkPixmap *
gdk_pixmap_colormap_create_from_xpm (GdkDrawable *drawable,
                                     GdkColormap *colormap,
                                     GdkBitmap **mask,
                                     const GdkColor *transparent_color,
                                     const gchar *filename);

gdk_pixmap_colormap_create_from_xpm has been deprecated since version 2.22 and should not be used in newly-written code.

Use a GdkPixbuf instead. You can use gdk_pixbuf_new_from_file() to create it. If you must use a pixmap, use gdk_pixmap_new() to create it and Cairo to draw the pixbuf onto it.

Create a pixmap from a XPM file using a particular colormap.

Parameters

drawable	a GdkDrawable, used to determine default values for the new pixmap. Can be `NULL` if `colormap` is given.
colormap	the GdkColormap that the new pixmap will be use. If omitted, the colormap for `window` will be used.
mask	a pointer to a place to store a bitmap representing the transparency mask of the XPM file. Can be `NULL`, in which case transparency will be ignored.
transparent_color	the color to be used for the pixels that are transparent in the input file. Can be `NULL`, in which case a default color will be used.
filename	the filename of a file containing XPM data.

Returns

the GdkPixmap.

[transfer none]

gdk_pixmap_create_from_xpm_d ()

GdkPixmap *
gdk_pixmap_create_from_xpm_d (GdkDrawable *drawable,
                              GdkBitmap **mask,
                              const GdkColor *transparent_color,
                              gchar **data);

gdk_pixmap_create_from_xpm_d has been deprecated since version 2.22 and should not be used in newly-written code.

Use a GdkPixbuf instead. You can use gdk_pixbuf_new_from_xpm_data() to create it. If you must use a pixmap, use gdk_pixmap_new() to create it and Cairo to draw the pixbuf onto it.

Create a pixmap from data in XPM format.

Parameters

drawable	a GdkDrawable, used to determine default values for the new pixmap.
mask	Pointer to a place to store a bitmap representing the transparency mask of the XPM file. Can be `NULL`, in which case transparency will be ignored.	[out]
transparent_color	This color will be used for the pixels that are transparent in the input file. Can be `NULL` in which case a default color will be used.
data	Pointer to a string containing the XPM data.

Returns

the GdkPixmap.

[transfer none]

gdk_pixmap_colormap_create_from_xpm_d ()

GdkPixmap *
gdk_pixmap_colormap_create_from_xpm_d (GdkDrawable *drawable,
                                       GdkColormap *colormap,
                                       GdkBitmap **mask,
                                       const GdkColor *transparent_color,
                                       gchar **data);

gdk_pixmap_colormap_create_from_xpm_d has been deprecated since version 2.22 and should not be used in newly-written code.

Use a GdkPixbuf instead. You can use gdk_pixbuf_new_from_xpm_data() to create it. If you must use a pixmap, use gdk_pixmap_new() to create it and Cairo to draw the pixbuf onto it.

Create a pixmap from data in XPM format using a particular colormap.

Parameters

drawable	a GdkDrawable, used to determine default values for the new pixmap. Can be `NULL` if `colormap` is given.
colormap	the GdkColormap that the new pixmap will be use. If omitted, the colormap for `window` will be used.
mask	a pointer to a place to store a bitmap representing the transparency mask of the XPM file. Can be `NULL`, in which case transparency will be ignored.
transparent_color	the color to be used for the pixels that are transparent in the input file. Can be `NULL`, in which case a default color will be used.
data	Pointer to a string containing the XPM data.

Returns

the GdkPixmap.

[transfer none]

gdk_pixmap_get_size ()

void
gdk_pixmap_get_size (GdkPixmap *pixmap,
                     gint *width,
                     gint *height);

This function is purely to make it possible to query the size of pixmaps even when compiling without deprecated symbols and you must use pixmaps. It is identical to gdk_drawable_get_size(), but for pixmaps.

Parameters

pixmap	a GdkPixmap
width	location to store `pixmap` 's width, or `NULL`.	[out][allow-none]
height	location to store `pixmap` 's height, or `NULL`.	[out][allow-none]

Since 2.24

Types and Values

GdkPixmap

typedef struct _GdkDrawable           GdkPixmap;

An opaque structure representing an offscreen drawable. Pointers to structures of type GdkPixmap, GdkBitmap, and GdkWindow, can often be used interchangeably. The type GdkDrawable refers generically to any of these types.

gdk_pixmap_ref

#define gdk_pixmap_ref                 g_object_ref

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

Deprecated equivalent of g_object_ref().

Returns

pixmap

gdk_pixmap_unref

#define gdk_pixmap_unref               g_object_unref

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

Deprecated equivalent of g_object_unref().

GdkBitmap

typedef struct _GdkDrawable           GdkBitmap;

An opaque structure representing an offscreen drawable of depth 1. Pointers to structures of type GdkPixmap, GdkBitmap, and GdkWindow, can often be used interchangeably. The type GdkDrawable refers generically to any of these types.

gdk_bitmap_ref

#define gdk_bitmap_ref                 g_object_ref

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

Deprecated equivalent of g_object_ref().

Returns

pixmap

gdk_bitmap_unref

#define gdk_bitmap_unref               g_object_unref

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

Deprecated equivalent of g_object_unref().