GdkRGB and Colormap independece

[Owen Taylor <otaylor redhat com>]

I've spent a bit of time in the last few days working on making GdkRGB
able to render into any colormap and visual.

This, in general, hasn't been very hard, but there are some API
questions that come up when you do it. The GdkRGB API is designed, in
general, to free the user from having to worry about colormaps by
assuming that the colormap is always the GdkRGB colormap.

The question is how to make it possible to use GdkGB with different
colormaps and visuals (this is necessary for things like rendering on
the root window), without reintroducing colormaps all over the
API:

The troublesome functions in GdkRGB can be represented by
the following set:

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

void gdk_rgb_gc_set_foreground (GdkGC *gc, guint32 rgb);
void gdk_rgb_gc_set_background (GdkGC *gc, guint32 rgb);

gulong gdk_rgb_xpixel_from_rgb (guint32 rgb);

gdk_draw_image() is the simple case, since drawables
frequently do have a an associated colormap. (All windows
have a colormap, and it is possible to set a colormap
on a pixmap.) The way I've handled it is to use the
drawable's colormap if has one, otherwise, if the depth
of the drawable matches the depth of the GdkRGB colormap,
to use that, otherwise simply print a warning.

The main problem people will have is if they write something
like:

 pixmap = gdk_pixmap_new (NULL,
                          gtk_widget_get_visual (widget)->depth);

They'd have to add:

  gdk_drawable_set_colormap (pixmap, gtk_widget_get_colormap (widget));

Since those two lines are rather cumbersome, I plan to add
a factory function to GtkWidget:

 GdkPixmap *gtk_widget_create_pixmap (gint width, gint height);

The solution I've come up for the gc_set_foreground() and
gc_set_background() functions is to add a colormap field
to a GC similar to that in a drawable. Since GC's are
created for a particular drawable (or for GtkStyle, for
a particular colormap), it's not going to be difficult
to get make sure that the GC contains an appropriate colormap.

(These functions don't fit the GTK+ API, so most likely they
will be augmented with something like:

 gdk_gc_set_rgb_fg_color (GdkGC *gc, GdkColor *color);
 gdk_gc_set_rgb_bg_color (GdkGC *gc, GdkColor *color);

which differ from gdk_gc_set_foreground() only in using GdkRGB
to find the color instead of taking an allocated color.)

gulong gdk_rgb_xpixel_from_rgb (guint32 rgb);

Is clearly not recoverable as is, so it will be left simply
using the default GdkRGB colormap, and a new function
added, something like:

 gdk_colormap_find_rgb_color (GdkColormap *colormap, GdkColor *color);

Two other other somewhat related changes I'm thinking about 
are:

 - Make gtk_widget_push_visual() a complete noop, and
   define gtk_widget_get_visual(widget)) as:

    gtk_colormap_get_visual (gtk_widget_get_colormap (widget))

   It's poor design that you currently have to push both the colormap
   and visual, but they have to match.

 - Make the default colormap for GTK+ the GdkRGB visual instead
   of the system default. Getting the visual right won't be
   as crucial as before since GdkRGB will handle things other
   than the default, but my feeling is that if we are using
   GdkRGB for all images, etc, we should make the default colormap
   the one in which GdkRGB feels most comfortable.

Comments?
                                        Owen