Replacing Imlib in the GNOME libraries

[Miguel de Icaza <miguel gnu org>]

[ This document is available in
  http://www.nuclecu.unam.mx/~miguel/gnome/imlib-replacement.txt 
] 

	
This is a roadmap for removing the Imlib dependency in the GNOME
libraries while remaining binary compatible.

I would like to get some discussion going on this topic.

* The replacement library
-------------------------

LibArt and gdk-pixbuf will provide the replacement functions that we
need to replace Imlib.

How the replacement library works:

	* ArtPixBuf types can contain images in RGB and RGBA formats,
	  this has the benefit over the current scheme that it can
	  keep the alpha channel of the image if this is available.

	  Contrast this with Imlib which discards the Alpha channel to
	  convert it into a one-bit transparency channel and uses
	  the "magic" magenta color for this.

	* gdk-pixbuf is a library that loads and saves images in a
	  number of graphic formats into an RGBA buffer (or RGB if no
	  alpha channel is available).

	* The actual images are loaded into ArtPixBuf data structures
	  (basically, a structure that wraps the big information chunk).

	* gdk-pixbuf contains API functions that provide scaling and
	  rotating of these RGBA, RGB buffers.  These routines are
	  wrappers around the actual rendering routines in
	  libart_lgpl.

	* Rendering of the RGB data is actually performed by the
	  existing GdkRGB code in GTK+.

* Benefits
----------

	* We get alpha transparency right for our image loading.
	  
	* We reuse the code from libart and the code from gdkrgb 

	* We *might* end up linking with fewer libraries.

	* We get more powerful image manipulation by reusing the 
	  LibArt code.

	* We get memory handling done properly for the first time
	  (enabling a number of features we have disabled in the file
	  manager due to the non-trivial memory-management of Imlib).
	
	* GdkRGB also handles the dithering for low end displays.  

	* We could in the future include an "imlib renderer" which
	  would be an alternate rendering engine to GdkRGB if we find
	  this is necessary.

* The compatibility functions
-----------------------------

Public functions that used to take a GdkImlibImage argument, will be
changed to take an ArtPixBuf image argument.

Then the GdkImlibImage-based routine will be placed in a compatibility
library that will do the GdkImlib to ArtPixBuf conversion.  Once the
conversion is done, the new foundation routine will be invoked.

* Functions affected
--------------------

Files that have to be migrated to the new scheme:
    gnome-animator.c
    gnome-canvas-image.c
    gnome-canvas-load.c
    
    gnome-druid-page-*.c
    gnome-pixmap.c

Functions that use Imlib internally:
    gnome-icon-entry.c
    gnome-stock.c

* The library split
-------------------

Here is where problems begin from the binary compatibility with older
software point of view.  

I think we can split gnomeui to address this.  For the purpose of this
discussion I will use some sample names: 

	libgnomeui-simple.a:
		Would contain only GdkPixBuf/ArtPixBuf code.
		No knowledge on GdkImlib at all.

	libgnomeui.a:
		Would be libgnomeui-simple.a plus the wrapper functions.

Does this sound good?

* 


Miguel.