gdk_rgb_init ()

void        gdk_rgb_init                    (void);

This function no longer does anything at all. It's completely useless (and harmless).

gdk_draw_rgb_image ()

void        gdk_draw_rgb_image              (GdkDrawable *drawable,
                                             GdkGC *gc,
                                             gint x,
                                             gint y,
                                             gint width,
                                             gint height,
                                             GdkRgbDither dith,
                                             guchar *rgb_buf,
                                             gint rowstride);

Draws an RGB image in the drawable. This is the core GdkRGB function, and likely the only one you will need to use.

The rowstride parameter allows for lines to be aligned more flexibly. For example, lines may be allocated to begin on 32-bit boundaries, even if the width of the rectangle is odd. Rowstride is also useful when drawing a subrectangle of a larger image in memory. Finally, to replicate the same line a number of times, the trick of setting rowstride to 0 is allowed.

In general, for 0 <= i < width and 0 <= j < height, the pixel (x + i, y + j) is colored with red value rgb_buf[j * rowstride + i * 3], green value rgb_buf[j * rowstride + i * 3 + 1], and blue value rgb_buf[j * rowstride + i * 3 + 2].

gdk_draw_rgb_image_dithalign ()

void        gdk_draw_rgb_image_dithalign    (GdkDrawable *drawable,
                                             GdkGC *gc,
                                             gint x,
                                             gint y,
                                             gint width,
                                             gint height,
                                             GdkRgbDither dith,
                                             guchar *rgb_buf,
                                             gint rowstride,
                                             gint xdith,
                                             gint ydith);

Draws an RGB image in the drawable, with an adjustment for dither alignment.

This function is useful when drawing dithered images into a window that may be scrolled. Pixel (x, y) will be drawn dithered as if its actual location is (x + xdith, y + ydith). Thus, if you draw an image into a window using zero dither alignment, then scroll up one pixel, subsequent draws to the window should have ydith = 1.

Setting the dither alignment correctly allows updating of small parts of the screen while avoiding visible "seams" between the different dither textures.

gdk_draw_indexed_image ()

void        gdk_draw_indexed_image          (GdkDrawable *drawable,
                                             GdkGC *gc,
                                             gint x,
                                             gint y,
                                             gint width,
                                             gint height,
                                             GdkRgbDither dith,
                                             guchar *buf,
                                             gint rowstride,
                                             GdkRgbCmap *cmap);

Draws an indexed image in the drawable, using a GdkRgbCmap to assign actual colors to the color indices.

gdk_draw_gray_image ()

void        gdk_draw_gray_image             (GdkDrawable *drawable,
                                             GdkGC *gc,
                                             gint x,
                                             gint y,
                                             gint width,
                                             gint height,
                                             GdkRgbDither dith,
                                             guchar *buf,
                                             gint rowstride);

Draws a grayscale image in the drawable.

gdk_draw_rgb_32_image ()

void        gdk_draw_rgb_32_image           (GdkDrawable *drawable,
                                             GdkGC *gc,
                                             gint x,
                                             gint y,
                                             gint width,
                                             gint height,
                                             GdkRgbDither dith,
                                             guchar *buf,
                                             gint rowstride);

Draws a padded RGB image in the drawable. The image is stored as one pixel per 32-bit word. It is laid out as a red byte, a green byte, a blue byte, and a padding byte.

It's unlikely that this function will give significant performance gains in practice. In my experience, the performance gain from having pixels aligned to 32-bit boundaries is cancelled out by the increased memory bandwidth.

gdk_draw_rgb_32_image_dithalign ()

void        gdk_draw_rgb_32_image_dithalign (GdkDrawable *drawable,
                                             GdkGC *gc,
                                             gint x,
                                             gint y,
                                             gint width,
                                             gint height,
                                             GdkRgbDither dith,
                                             guchar *buf,
                                             gint rowstride,
                                             gint xdith,
                                             gint ydith);

Like gdk_draw_rgb_32_image(), but allows you to specify the dither offsets. See gdk_draw_rgb_image_dithalign() for more details.

enum GdkRgbDither

typedef enum
{
  GDK_RGB_DITHER_NONE,
  GDK_RGB_DITHER_NORMAL,
  GDK_RGB_DITHER_MAX
} GdkRgbDither;

Selects whether or not GdkRGB applies dithering to the image on display. There are three values:

Since GdkRGB currently only handles images with 8 bits per component, dithering on 24 bit per pixel displays is a moot point.

gdk_rgb_cmap_new ()

GdkRgbCmap* gdk_rgb_cmap_new                (guint32 *colors,
                                             gint n_colors);

Creates a new GdkRgbCmap structure. The cmap maps color indexes to RGB colors. If n_colors is less than 256, then images containing color values greater than or equal to n_colors will produce undefined results, including possibly segfaults.

gdk_rgb_cmap_free ()

void        gdk_rgb_cmap_free               (GdkRgbCmap *cmap);

Frees the memory associated with a GdkRgbCmap created by gdk_rgb_cmap_new().

GdkRgbCmap

typedef struct {
  guint32 colors[256];
  gint n_colors;
} GdkRgbCmap;

A private data structure which maps color indices to actual RGB colors. This is used only for gdk_draw_indexed_image().

gdk_rgb_gc_set_foreground ()

void        gdk_rgb_gc_set_foreground       (GdkGC *gc,
                                             guint32 rgb);

Sets the foreground color in gc to the specified color (or the closest approximation, in the case of limited visuals).

gdk_rgb_gc_set_background ()

void        gdk_rgb_gc_set_background       (GdkGC *gc,
                                             guint32 rgb);

Sets the background color in gc to the specified color (or the closest approximation, in the case of limited visuals).

gdk_rgb_xpixel_from_rgb ()

gulong      gdk_rgb_xpixel_from_rgb         (guint32 rgb);

Finds the X pixel closest in color to the rgb color specified. This value may be used to set the pixel field of a GdkColor struct.

gdk_rgb_find_color ()

void        gdk_rgb_find_color              (GdkColormap *colormap,
                                             GdkColor *color);

colormap should be the colormap for the graphics context and drawable you're using to draw. If you're drawing to a GtkWidget, call gtk_widget_get_colormap().

color should have its red, green, and blue fields initialized; gdk_rgb_find_color() will fill in the pixel field with the best matching pixel from a color cube. The color is then ready to be used for drawing, e.g. you can call gdk_gc_set_foreground() which expects pixel to be initialized.

In many cases, you can avoid this whole issue by calling gdk_gc_set_rgb_fg_color() or gdk_gc_set_rgb_bg_color(), which do not expect pixel to be initialized in advance. If you use those functions, there's no need for gdk_rgb_find_color().

gdk_rgb_set_install ()

void        gdk_rgb_set_install             (gboolean install);

If install is TRUE, directs GdkRGB to always install a new "private" colormap rather than trying to find a best fit with the colors already allocated. Ordinarily, GdkRGB will install a colormap only if a sufficient cube cannot be allocated.

A private colormap has more colors, leading to better quality display, but also leads to the dreaded "colormap flashing" effect.

gdk_rgb_set_min_colors ()

void        gdk_rgb_set_min_colors          (gint min_colors);

Sets the minimum number of colors for the color cube. Generally, GdkRGB tries to allocate the largest color cube it can. If it can't allocate a color cube at least as large as min_colors, it installs a private colormap.

gdk_rgb_get_visual ()

GdkVisual*  gdk_rgb_get_visual              (void);

Gets a "preferred visual" chosen by GdkRGB for rendering image data on the default screen. In previous versions of GDK, this was the only visual GdkRGB could use for rendering. In current versions, it's simply the visual GdkRGB would have chosen as the optimal one in those previous versions. GdkRGB can now render to drawables with any visual.

gdk_rgb_get_colormap ()

GdkColormap* gdk_rgb_get_colormap           (void);

Get the preferred colormap for rendering image data. Not a very useful function; historically, GDK could only render RGB image data to one colormap and visual, but in the current version it can render to any colormap and visual. So there's no need to call this function.

gdk_rgb_get_cmap

#define gdk_rgb_get_cmap               gdk_rgb_get_colormap

Gets the colormap set by GdkRGB. This colormap and the corresponding visual should be used when creating windows that will be drawn in by GdkRGB.

gdk_rgb_ditherable ()

gboolean    gdk_rgb_ditherable              (void);

Determines whether the preferred visual is ditherable. This function may be useful for presenting a user interface choice to the user about which dither mode is desired; if the display is not ditherable, it may make sense to gray out or hide the corresponding UI widget.

gdk_rgb_colormap_ditherable ()

gboolean    gdk_rgb_colormap_ditherable     (GdkColormap *cmap);

Determines whether the visual associated with cmap is ditherable. This function may be useful for presenting a user interface choice to the user about which dither mode is desired; if the display is not ditherable, it may make sense to gray out or hide the corresponding UI widget.

gdk_rgb_set_verbose ()

void        gdk_rgb_set_verbose             (gboolean verbose);

Sets the "verbose" flag. This is generally only useful for debugging.