gtk2/docs/reference/gdk-pixbuf/porting-from-imlib.sgml
Matthias Clasen 8e2de76673 Remove references to deprecated functions. (#460207, Guillaume Cottenceau)
2007-09-06  Matthias Clasen  <mclasen@redhat.com>

        * gdk-pixbuf/porting-from-imlib.sgml:
        * gdk/tmpl/rgb.sgml: Remove references to deprecated
        functions.  (#460207, Guillaume Cottenceau)



svn path=/trunk/; revision=18741
2007-09-07 03:18:53 +00:00

353 lines
11 KiB
Plaintext

<appendix>
<title>Porting applications from &Imlib; to &gdk-pixbuf;</title>
<para>
This appendix contains the basic steps needed to port an
application that uses the &Imlib; library to use &gdk-pixbuf;
instead.
</para>
<note>
<para>
This appendix refers to version 1 of the &Imlib; library; this
discussion is not relevant to Imlib 2. Also, we discuss the
gdk_imlib API instead of the Xlib-based API.
</para>
</note>
<!-- Introduction -->
<sect1>
<title>Introduction</title>
<para>
Prior to the GNOME 1.2 platform, the &Imlib; library was the
preferred way of loading and rendering images in GNOME
applications. Unfortunately, &Imlib; has important design
limitations that make it hard to write efficient and highly
modular applications.
</para>
<para>
The &gdk-pixbuf; library was designed as a solution to
&Imlib;'s shortcomings. It provides a simple, orthogonal API
and convenience functions for the most common operations. In
addition, it supports full transparency information for
images, or alpha channel. More importantly, it has
well-defined semantics for memory management through the use
of reference counting; &Imlib; has an intractably complex
memory management mechanism and cache that will make your head
spin.
</para>
</sect1>
<!-- Differences between Imlib and gdk-pixbuf -->
<sect1>
<title>Differences between &Imlib; and &gdk-pixbuf;</title>
<para>
Generally, applications that use &Imlib; do not have to be
changed extensively to use &gdk-pixbuf;; its simple and
flexible API makes things easy. This section describes the
differences between &Imlib; and &gdk-pixbuf;; you should take
these into account when modifying your applications to use
&gdk-pixbuf;.
</para>
<!-- Initialization -->
<sect2>
<title>Initialization</title>
<para>
The &gdk-pixbuf; library does not need to be initialized.
</para>
<note>
<para>
In GNOME applications you normally don't need to
initialize &Imlib;, as <function>gnome_init()</function>
calls <function>gdk_imlib_init()</function> automatically.
</para>
</note>
</sect2>
<!-- Memory management -->
<sect2>
<title>Memory management</title>
<para>
The &gdk-pixbuf; library provides a simple, well-defined
memory management mechanism for images in the form of
reference counting. This makes it very convenient to use
for large-scale applications that need to share images
between different parts of the program. In stark contrast,
&Imlib; has a terribly complex mechanism of an image and
pixmap cache which makes it very hard for applications to
share image structures between different parts of the
program. Unfortunately this mechanism makes things very
prone to memory leaks and tricky bugs.
</para>
<para>
The basic principle in &gdk-pixbuf; is that when you obtain
a new <link linkend="GdkPixbuf">GdkPixbuf</link> structure,
it is created with an initial reference count of 1. When
another part of the program wants to keep a reference to the
pixbuf, it should call <function>g_object_ref()</function>;
this will increase the reference count by 1. When some part
of the program does not need to keep a reference to a pixbuf
anymore and wants to release the pixbuf, it should call
<function>g_object_unref()</function>; this will decrease
the reference count by 1. When the reference count drops to
zero, the pixbuf gets destroyed or
<emphasis>finalized</emphasis> and its memory is freed.
</para>
<para>
For applications that need to implement a cache of loaded
images, &gdk-pixbuf; provides a way to hook to the last
unreference operation of a pixbuf; instead of finalizing the
pixbuf, the user-installed hook can decide to keep it around
in a cache instead.
</para>
<para>
Finally, &gdk-pixbuf; does not provide a cache of rendered
pixmaps. This is unnecessary for most applications, since
the scaling and rendering functions are quite fast and
applications may need to use subtly different values each
time they call these functions, for example, to take into
account dithering and zooming offsets.
</para>
<para>
Most applications will simply need to call
<function>g_object_ref()</function> when they want to keep
an extra reference to a pixbuf, and then
<function>g_object_unref()</function> when they are done
with it.
</para>
</sect2>
<!-- The Rendering Process -->
<sect2>
<title>The Rendering Process</title>
<para>
The &gdk-pixbuf; library has the policy of always rendering
pixbufs to GDK drawables you provide; it will not create
them for you. This is in general more flexible than
&Imlib;'s policy of always creating a pixmap and making you
use that instead.
</para>
<para>
The disadvantage of always having a pixmap created for you
is that it wastes memory in the X server if you intend to
copy that rendered data onto another drawable, for example,
the final destination window or a temporary pixmap for
drawing. This is the most common case, unfortunately, so
the &Imlib; policy introduces unnecessary copying.
</para>
<para>
Also, &Imlib; can only render pixmaps that are the whole
size of the source image; you cannot render just a subset
region of the image. This is inconvenient for applications
that need to render small portions at a time, such as
applications that do scrolling. Since the whole image must
be rendered at a time, this can lead to performance and
memory usage problems.
</para>
<para>
The &gdk-pixbuf; library lets you render any rectangular
region from an image onto any drawable that you provide.
This lets the application have fine control the way images
are rendered.
</para>
</sect2>
</sect1>
<!-- Converting Applications to gdk-pixbuf -->
<sect1>
<title>Converting Applications to &gdk-pixbuf;</title>
<para>
This sections describes the actual changes you need to make in
an &Imlib; program to make it use &gdk-pixbuf; instead.
</para>
<!-- Image loading and creation -->
<sect2>
<title>Image loading and creation</title>
<para>
The &gdk-pixbuf; library can load image files synchronously
(i.e. with a single function call), create images from RGB
data in memory, and as a convenience, it can also create
images from inline XPM data.
</para>
<para>
To load an image file in a single function call, simply use
<function>gdk_pixbuf_new_from_file()</function>. Note that
this will make the program block until the whole file has
been read. This function effectively replaces
<function>gdk_imlib_load_image()</function>.
</para>
<para>
If you have RGB data in memory, you can use
<function>gdk_pixbuf_new_from_data()</function> to create a
pixbuf out of it; this is a replacement for
<function>gdk_imlib_create_image_from_data()</function>.
&gdk-pixbuf; does not copy the image data; it is up to you
to define the ownership policy by providing a destroy
notification function that will be called when the image
data needs to be freed. The function you provide can then
free the data or do something else, as appropriate.
</para>
<para>
As a convenience, you can use the
<function>gdk_pixbuf_new_from_xpm_data()</function> function
to create a pixbuf out of inline XPM data that was compiled
into your C program. This is a replacement for
<function>gdk_imlib_create_image_from_xpm_data()</function>.
</para>
<para>
After you have created a pixbuf, you can manipulate it in
any way you please and then finally call
<function>g_object_unref()</function> when you are done
with it. This can be thought of as a replacement for
<function>gdk_imlib_destroy_image()</function> but with much
cleaner semantics.
</para>
</sect2>
<!-- Rendering Images -->
<sect2>
<title>Rendering Images</title>
<para>
Applications that use &Imlib; must first call
<function>gdk_imlib_render()</function> to render the whole
image data onto a pixmap that &Imlib; creates. Then they
must copy that pixmap's data into the final destination for
the image.
</para>
<para>
In contrast, &gdk-pixbuf; provides convenience functions to
render arbitrary rectangular regions of an image onto a
drawable that your application provides. You can use
<function>gdk_draw_pixbuf()</function> to do this; having
your application provide the destination drawable and
specify an arbitrary region means your application has
complete control over the way images are rendered.
</para>
<para>
As a convenience, &gdk-pixbuf; also provides the
<function>gdk_pixbuf_render_pixmap_and_mask()</function>
function; this will create new pixmap and mask drawables for
a whole pixbuf and render the image data onto them. Only
trivially simple applications should find a use for this
function, since usually you want finer control of how things
are rendered.
</para>
</sect2>
<!-- Scaling Images -->
<sect2>
<title>Scaling Images</title>
<para>
&Imlib; lets you render scaled image data at the time you
call <function>gdk_imlib_render()</function>. Again, this
unfortunately scales and renders the whole image onto a new
pixmap.
</para>
<para>
&gdk-pixbuf; provides a number of functions that do scaling
of arbitrary regions of a source pixbuf onto a destination
one. These functions can also perform compositing
operations against the data in the destination pixbuf or
against a solid color or a colored checkerboard.
<footnote>
<para>
You can use a colored checkerboard as the background for
compositing when you want to provide a visual indication
that the image has partially opaque areas. This is
normally used in image editing and viewing programs.
</para>
<para>
Compositing against a single solid color is actually a
special case of a checkerboard; it simply uses checks of
the same color.
</para>
</footnote>
</para>
<para>
Very simple applications may find it sufficient to use
<function>gdk_pixbuf_scale_simple()</function> or
<function>gdk_pixbuf_composite_color_simple()</function>.
These functions scale the whole source image at a time and
create a new pixbuf with the result.
</para>
<para>
More sophisticated applications will need to use
<function>gdk_pixbuf_scale()</function>,
<function>gdk_pixbuf_composite()</function>, or
<function>gdk_pixbuf_composite_color()</function> instead.
These functions let you scale and composite an arbitrary
region of the source pixbuf onto a destination pixbuf that
you provide.
</para>
</sect2>
<!-- Getting Image Data from a Drawable -->
<sect2>
<title>Getting Image Data from a Drawable</title>
<para>
&Imlib; lets you create an image by fetching a drawable's
contents from the X server and converting those into RGB
data. This is done with the
<function>gdk_imlib_create_image_from_drawable()</function>
function.
</para>
<para>
&gdk-pixbuf; provides the
<function>gdk_pixbuf_get_from_drawable()</function> function
instead. It lets you specify a destination pixbuf instead
of always creating a new one for you.
</para>
</sect2>
</sect1>
</appendix>
<!--
Local variables:
mode: sgml
sgml-parent-document: ("gdk-pixbuf.sgml" "book" "book" "")
End:
-->