2
<title>Porting applications from &Imlib; to &gdk-pixbuf;</title>
5
This appendix contains the basic steps needed to port an
6
application that uses the &Imlib; library to use &gdk-pixbuf;
12
This appendix refers to version 1 of the &Imlib; library; this
13
discussion is not relevant to Imlib 2. Also, we discuss the
14
gdk_imlib API instead of the Xlib-based API.
21
<title>Introduction</title>
24
Prior to the GNOME 1.2 platform, the &Imlib; library was the
25
preferred way of loading and rendering images in GNOME
26
applications. Unfortunately, &Imlib; has important design
27
limitations that make it hard to write efficient and highly
32
The &gdk-pixbuf; library was designed as a solution to
33
&Imlib;'s shortcomings. It provides a simple, orthogonal API
34
and convenience functions for the most common operations. In
35
addition, it supports full transparency information for
36
images, or alpha channel. More importantly, it has
37
well-defined semantics for memory management through the use
38
of reference counting; &Imlib; has an intractably complex
39
memory management mechanism and cache that will make your head
44
<!-- Differences between Imlib and gdk-pixbuf -->
47
<title>Differences between &Imlib; and &gdk-pixbuf;</title>
50
Generally, applications that use &Imlib; do not have to be
51
changed extensively to use &gdk-pixbuf;; its simple and
52
flexible API makes things easy. This section describes the
53
differences between &Imlib; and &gdk-pixbuf;; you should take
54
these into account when modifying your applications to use
58
<!-- Initialization -->
61
<title>Initialization</title>
64
The &gdk-pixbuf; library does not need to be initialized.
65
However, if you intend to use the rendering functions or
66
anything else from the <application>GdkRGB</application>
67
library, you should call <function>gdk_rgb_init()</function>
68
after calling <function>gtk_init()</function> or
69
<function>gnome_init()</function> in your program.
74
In GNOME applications you normally don't need to
75
initialize &Imlib;, as <function>gnome_init()</function>
76
calls <function>gdk_imlib_init()</function> automatically.
81
<!-- Memory management -->
84
<title>Memory management</title>
87
The &gdk-pixbuf; library provides a simple, well-defined
88
memory management mechanism for images in the form of
89
reference counting. This makes it very convenient to use
90
for large-scale applications that need to share images
91
between different parts of the program. In stark contrast,
92
&Imlib; has a terribly complex mechanism of an image and
93
pixmap cache which makes it very hard for applications to
94
share image structures between different parts of the
95
program. Unfortunately this mechanism makes things very
96
prone to memory leaks and tricky bugs.
100
The basic principle in &gdk-pixbuf; is that when you obtain
101
a new <link linkend="GdkPixbuf">GdkPixbuf</link> structure,
102
it is created with an initial reference count of 1. When
103
another part of the program wants to keep a reference to the
104
pixbuf, it should call <link
105
linkend="gdk-pixbuf-ref">gdk_pixbuf_ref()</link>; this will
106
increase the reference count by 1. When some part of the
107
program does not need to keep a reference to a pixbuf
108
anymore and wants to release the pixbuf, it should call
109
<link linkend="gdk-pixbuf-unref">gdk_pixbuf_unref()</link>;
110
this will decrease the reference count by 1. When the
111
reference count drops to zero, the pixbuf gets destroyed or
112
<emphasis>finalized</emphasis> and its memory is freed.
116
For applications that need to implement a cache of loaded
117
images, &gdk-pixbuf; provides a way to hook to the last
118
unreference operation of a pixbuf; instead of finalizing the
119
pixbuf, the user-installed hook can decide to keep it around
124
Finally, &gdk-pixbuf; does not provide a cache of rendered
125
pixmaps. This is unnecessary for most applications, since
126
the scaling and rendering functions are quite fast and
127
applications may need to use subtly different values each
128
time they call these functions, for example, to take into
129
account dithering and zooming offsets.
133
Most applications will simply need to call
134
<function>gdk_pixbuf_ref()</function> when they want to keep
135
an extra reference to a pixbuf, and then
136
<function>gdk_pixbuf_unref()</function> when they are done
141
<!-- The Rendering Process -->
144
<title>The Rendering Process</title>
147
The &gdk-pixbuf; library has the policy of always rendering
148
pixbufs to Gdk drawables you provide; it will not create
149
them for you. This is in general more flexible than
150
&Imlib;'s policy of always creating a pixmap and making you
155
The disadvantage of always having a pixmap created for you
156
is that it wastes memory in the X server if you intend to
157
copy that rendered data onto another drawable, for example,
158
the final destination window or a temporary pixmap for
159
drawing. This is the most common case, unfortunately, so
160
the &Imlib; policy introduces unnecessary copying.
164
Also, &Imlib; can only render pixmaps that are the whole
165
size of the source image; you cannot render just a subset
166
region of the image. This is inconvenient for applications
167
that need to render small portions at a time, such as
168
applications that do scrolling. Since the whole image must
169
be rendered at a time, this can lead to performance and
170
memory usage problems.
174
The &gdk-pixbuf; library lets you render any rectangular
175
region from an image onto any drawable that you provide.
176
This lets the application have fine control the way images
182
<!-- Converting Applications to gdk-pixbuf -->
185
<title>Converting Applications to &gdk-pixbuf;</title>
188
This sections describes the actual changes you need to make in
189
an &Imlib; program to make it use &gdk-pixbuf; instead.
192
<!-- Image loading and creation -->
195
<title>Image loading and creation</title>
198
The &gdk-pixbuf; library can load image files synchronously
199
(i.e. with a single function call), create images from RGB
200
data in memory, and as a convenience, it can also create
201
images from inline XPM data.
205
To load an image file in a single function call, simply use
206
<function>gdk_pixbuf_new_from_file()</function>. Note that
207
this will make the program block until the whole file has
208
been read. This function effectively replaces
209
<function>gdk_imlib_load_image()</function>.
213
If you have RGB data in memory, you can use
214
<function>gdk_pixbuf_new_from_data()</function> to create a
215
pixbuf out of it; this is a replacement for
216
<function>gdk_imlib_create_image_from_data()</function>.
217
&gdk-pixbuf; does not copy the image data; it is up to you
218
to define the ownership policy by providing a destroy
219
notification function that will be called when the image
220
data needs to be freed. The function you provide can then
221
free the data or do something else, as appropriate.
225
As a convenience, you can use the
226
<function>gdk_pixbuf_new_from_xpm_data()</function> function
227
to create a pixbuf out of inline XPM data that was compiled
228
into your C program. This is a replacement for
229
<function>gdk_imlib_create_image_from_xpm_data()</function>.
233
After you have created a pixbuf, you can manipulate it in
234
any way you please and then finally call
235
<function>gdk_pixbuf_unref()</function> when you are done
236
with it. This can be thought of as a replacement for
237
<function>gdk_imlib_destroy_image()</function> but with much
242
<!-- Rendering Images -->
245
<title>Rendering Images</title>
248
Applications that use &Imlib; must first call
249
<function>gdk_imlib_render()</function> to render the whole
250
image data onto a pixmap that &Imlib; creates. Then they
251
must copy that pixmap's data into the final destination for
256
In contrast, &gdk-pixbuf; provides convenience functions to
257
render arbitrary rectangular regions of an image onto a
258
drawable that your application provides. You can use
259
<function>gdk_pixbuf_render_to_drawable()</function> or
260
<function>gdk_pixbuf_render_to_drawable_alpha()</function>
261
to do this; having your application provide the destination
262
drawable and specify an arbitrary region means your
263
application has complete control over the way images are
268
As a convenience, &gdk-pixbuf; also provides the
269
<function>gdk_pixbuf_render_pixmap_and_mask()</function>
270
function; this will create new pixmap and mask drawables for
271
a whole pixbuf and render the image data onto them. Only
272
trivially simple applications should find a use for this
273
function, since usually you want finer control of how things
278
<!-- Scaling Images -->
281
<title>Scaling Images</title>
284
&Imlib; lets you render scaled image data at the time you
285
call <function>gdk_imlib_render()</function>. Again, this
286
unfortunately scales and renders the whole image onto a new
291
&gdk-pixbuf; provides a number of functions that do scaling
292
of arbitrary regions of a source pixbuf onto a destination
293
one. These functions can also perform compositing
294
operations against the data in the destination pixbuf or
295
against a solid color or a colored checkerboard.
298
You can use a colored checkerboard as the background for
299
compositing when you want to provide a visual indication
300
that the image has partially opaque areas. This is
301
normally used in image editing and viewing programs.
305
Compositing against a single solid color is actually a
306
special case of a checkerboard; it simply uses checks of
313
Very simple applications may find it sufficient to use
314
<function>gdk_pixbuf_scale_simple()</function> or
315
<function>gdk_pixbuf_composite_color_simple()</function>.
316
These functions scale the whole source image at a time and
317
create a new pixbuf with the result.
321
More sophisticated applications will need to use
322
<function>gdk_pixbuf_scale()</function>,
323
<function>gdk_pixbuf_composite()</function>, or
324
<function>gdk_pixbuf_composite_color()</function> instead.
325
These functions let you scale and composite an arbitrary
326
region of the source pixbuf onto a destination pixbuf that
331
<!-- Getting Image Data from a Drawable -->
334
<title>Getting Image Data from a Drawable</title>
337
&Imlib; lets you create an image by fetching a drawable's
338
contents from the X server and converting those into RGB
339
data. This is done with the
340
<function>gdk_imlib_create_image_from_drawable()</function>
345
&gdk-pixbuf; provides the
346
<function>gdk_pixbuf_get_from_drawable()</function> function
347
instead. It lets you specify a destination pixbuf instead
348
of always creating a new one for you.
357
sgml-parent-document: ("gdk-pixbuf.sgml" "book" "book" "")
added
removed
doc/porting-from-imlib.sgml
