Next: , Previous: Bitmaps and Pixmaps, Up: Top


10 GdkRGB

Renders RGB, grayscale, or indexed image data to a GdkDrawable

10.1 Overview

GdkRGB is a low-level module which renders RGB, grayscale, and indexed colormap images to a <gdk-drawable>. It does this as efficiently as possible, handling issues such as colormaps, visuals, dithering, temporary buffers, and so on. Most code should use the higher-level <gdk-pixbuf> features in place of this module; for example, gdk-pixbuf-render-to-drawable uses GdkRGB in its implementation.

GdkRGB allocates a color cube to use when rendering images. You can set the threshold for installing colormaps with gdk-rgb-set-min-colors. The default is 5x5x5 (125). If a colorcube of this size or larger can be allocated in the default colormap, then that's done. Otherwise, GdkRGB creates its own private colormap. Setting it to 0 means that it always tries to use the default colormap, and setting it to 216 means that it always creates a private one if it cannot allocate the 6x6x6 colormap in the default. If you always want a private colormap (to avoid consuming too many colormap entries for other apps, say), you can use ‘gdk_rgb_set_install(TRUE)’. Setting the value greater than 216 exercises a bug in older versions of GdkRGB. Note, however, that setting it to 0 doesn't let you get away with ignoring the colormap and visual - a colormap is always created in grayscale and direct color modes, and the visual is changed in cases where a "better" visual than the default is available.

     
     &#x0023;include <gtk/gtk.h>
     
     &#x0023;define IMAGE_WIDTH	256
     &#x0023;define IMAGE_HEIGHT	256
     
     guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
     
     gboolean on_darea_expose (GtkWidget *widget,
     			  GdkEventExpose *event,
     			  gpointer user_data);
     
     int
     main (int argc, char *argv[])
     {
       GtkWidget *window, *darea;
       gint x, y;
       guchar *pos;
     
       gtk_init (&argc, &argv);
     
       window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
       darea = gtk_drawing_area_new ();
       gtk_widget_set_size_request (darea, IMAGE_WIDTH, IMAGE_HEIGHT);
       gtk_container_add (GTK_CONTAINER (window), darea);
       gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
                           GTK_SIGNAL_FUNC (on_darea_expose), NULL);
       gtk_widget_show_all (window);
     
       /* Set up the RGB buffer. */
       pos = rgbbuf;
       for (y = 0; y < IMAGE_HEIGHT; y++)
         {
           for (x = 0; x < IMAGE_WIDTH; x++)
     	{
     	  *pos++ = x - x % 32;			/* Red. */
     	  *pos++ = (x / 32) * 4 + y - y % 32;	/* Green. */
     	  *pos++ = y - y % 32;			/* Blue. */
     	}
         }
     
       gtk_main ();
       return 0;
     }
     
     
     gboolean
     on_darea_expose (GtkWidget *widget,
     		 GdkEventExpose *event,
     		 gpointer user_data)
     {
       gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
     		      0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
     		      GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
     
       return TRUE;
     }

10.2 Usage

— Function: gdk-rgb-init

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

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

— Function: gdk-rgb-gc-set-foreground (gc <gdk-gc>) (rgb unsigned-int32)

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

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

gc
The <gdk-gc> to modify.
rgb
The color, represented as a 0xRRGGBB integer value.
— Function: gdk-rgb-gc-set-background (gc <gdk-gc>) (rgb unsigned-int32)

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

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

gc
The <gdk-gc> to modify.
rgb
The color, represented as a 0xRRGGBB integer value.
— Function: gdk-rgb-xpixel-from-rgb (rgb unsigned-int32) ⇒  (ret unsigned-long)

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

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

rgb
The color, represented as a 0xRRGGBB integer value.
ret
The X pixel value.
— Function: gdk-rgb-set-install (install bool)

If install is ‘#t’, 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.

install
#t’ to set install mode.
— Function: gdk-rgb-set-min-colors (min_colors int)

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.

min-colors
The minimum number of colors accepted.
— Function: gdk-rgb-get-visual ⇒  (ret <gdk-visual>)

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.

ret
The <gdk-visual> chosen by GdkRGB.
— Function: gdk-rgb-get-colormap ⇒  (ret <gdk-colormap>)

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.

ret
the preferred colormap
— Function: gdk-rgb-ditherable ⇒  (ret bool)

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.

ret
#t’ if the preferred visual is ditherable.
— Function: gdk-rgb-colormap-ditherable (cmap <gdk-colormap>) ⇒  (ret bool)

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.

cmap
a <gdk-colormap>
ret
#t’ if the visual associated with cmap is ditherable.
— Function: gdk-rgb-set-verbose (verbose bool)

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

verbose
#t’ if verbose messages are desired.