rendering-cleanup Part 2

[Benjamin Otte <otte gnome org>]

Hey everybody,

the second part of my GTK 3 rendering-cleanup work is done and is (as
always) available at
http://git.gnome.org/browse/gtk+/log/?h=rendering-cleanup Note that
after every commit the branch is fully compiling and working.
This work only touches GTK3 and will not effect GTK 2.22. I'll do
eventual GTK2 deprecatipons for it with GTK 2.24.

The stated goal for this part was the removal of GdkColormap and
GdkPixmap. Both of these goals have been reached, but I needed to do
things that I hoped would only be part of part3, the introduction of
gtk_widget_draw().
GdkPixmap was to be replaced by cairo_surface_t usage and GdkColormap
functionality was either removed because it is outdated or replaced by
GdkVisual.

I'll add some overview on API changes here and my intentions with
them. For the exact patches and more details, you'll need to look into
git. Commits that change API start with the tag "API:".

* Get rid of the Pixmap option when a Pixbuf option exists
A lot of APIs have versions taking either a Pixmap or a Pixbuf. Most
of the time, the pixbuf version is the only one that is used in
practice. In those cases, I removed the Pixmap version. If people
still use them, they can use gdk_pixbuf_get_from_drawable() or similar
to convert to a pixbuf. Examples are GtkImage or GdkCursor.
In the cases where such usage was expected to be common, I replaced
the GdkPixmap version with a cairo_surface_t version. The only example
that comes to mind is DND.

* Replace GdkPixmap/GdkBitmap usage with appropriate equivalents
This looks pretty straightforward, and it usually is: The GdkPixmap
version is replaced with a cairo_surface_t version. However, there
were some cases where I thought I could do better than a
straightforward conversion. In particular:
- Setting a shape is done internally using a region, so I exposed that
API instead. Plus I added a function called
gdk_cairo_region_create_from_surface() that does what it says using
50% alpha as the threshold.
- I removed all functions that take or produce a pixmap and a mask and
replaced them with versions that use any cairo_surface_t. The fact
that X11 has APIs that require such features is an implementation
detail. The GDK code then does the conversion internally if necessary.

* Change GTK vfuncs to take a cairo_t instead of a GdkWindow
The changed vfuncs are GtkCellRender->render and all the GtkStyle
render vfuncs. I didn't originally intend to do it this early, but
removing pixmaps would have meant I couldn't draw to anything but
windows anymore, and this is necessary for widgets (most notably
GtkTreeView and GtkTextView) to create dnd icons.
I did not change the API of the actual functions -
gtk_paint_foo()/gtk_cell_renderer_render() - but instead added new
functions - gtk_cairo_paint_foo()/gtk_cell_renderer_render_cairo() -
so I can do the transition step by step. The old functions still exist
and just forward to the new functions, but will go away before 3.0.
They're just supposed to be here to make the transition work easy.

* gtk_widget_get_snapshot() is gone
Equivalent functionality will come back with gtk_widget_draw(). For
now, it's gone, because we can't send expose events containing a
GdkPixmap anymore, so we always have to render to a GdkWindow.

* Make GtkWidget not use colormaps, but visuals
In GTK2, if you want your widget to create a GdkWindow on a
nonstandard visual, you'd have modified the widgets colormap. The most
well known use case is gtk_widget_set_colormap (window,
gdk_screen_get_rgba_colormap (gdk_screen_get_default ()) to get
translucent windows. In GTK3 this has been replaced by using visuals
instead. After consulting with people (thanks Owen!), I also decided
to only add API for setting the visual on toplevels and inherit them
down the stack. So the new code to get translucent windows looks like
this: gtk_window_set_visual (window, gdk_screen_get_rgba_visual
(gdk_screen_get_default ()). As a side effect, the tray icon code got
simpler. Woohoo!

That's about it. Comments?

Benjamin