1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Converting Applications to gdk-pixbuf</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="GDK-PixBuf Reference Manual">
<link rel="up" href="apa.html" title="Appendix A. Porting applications from Imlib to gdk-pixbuf">
<link rel="prev" href="apas02.html" title="Differences between Imlib and gdk-pixbuf">
<link rel="next" href="license.html" title="Appendix B. License">
<meta name="generator" content="GTK-Doc V1.14 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="apas02.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="apa.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GDK-PixBuf Reference Manual</th>
<td><a accesskey="n" href="license.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="sect1" title="Converting Applications to gdk-pixbuf">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id517491"></a>Converting Applications to <span class="application">gdk-pixbuf</span>
</h2></div></div></div>
<p>
This sections describes the actual changes you need to make in
an <span class="application">Imlib</span> program to make it use <span class="application">gdk-pixbuf</span> instead.
</p>
<div class="sect2" title="Image loading and creation">
<div class="titlepage"><div><div><h3 class="title">
<a name="id517520"></a>Image loading and creation</h3></div></div></div>
<p>
The <span class="application">gdk-pixbuf</span> 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.
</p>
<p>
To load an image file in a single function call, simply use
<code class="function">gdk_pixbuf_new_from_file()</code>. Note that
this will make the program block until the whole file has
been read. This function effectively replaces
<code class="function">gdk_imlib_load_image()</code>.
</p>
<p>
If you have RGB data in memory, you can use
<code class="function">gdk_pixbuf_new_from_data()</code> to create a
pixbuf out of it; this is a replacement for
<code class="function">gdk_imlib_create_image_from_data()</code>.
<span class="application">gdk-pixbuf</span> 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.
</p>
<p>
As a convenience, you can use the
<code class="function">gdk_pixbuf_new_from_xpm_data()</code> function
to create a pixbuf out of inline XPM data that was compiled
into your C program. This is a replacement for
<code class="function">gdk_imlib_create_image_from_xpm_data()</code>.
</p>
<p>
After you have created a pixbuf, you can manipulate it in
any way you please and then finally call
<code class="function">g_object_unref()</code> when you are done
with it. This can be thought of as a replacement for
<code class="function">gdk_imlib_destroy_image()</code> but with much
cleaner semantics.
</p>
</div>
<div class="sect2" title="Rendering Images">
<div class="titlepage"><div><div><h3 class="title">
<a name="id516581"></a>Rendering Images</h3></div></div></div>
<p>
Applications that use <span class="application">Imlib</span> must first call
<code class="function">gdk_imlib_render()</code> to render the whole
image data onto a pixmap that <span class="application">Imlib</span> creates. Then they
must copy that pixmap's data into the final destination for
the image.
</p>
<p>
In contrast, <span class="application">gdk-pixbuf</span> provides convenience functions to
render arbitrary rectangular regions of an image onto a
drawable that your application provides. You can use
<code class="function">gdk_draw_pixbuf()</code> 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.
</p>
<p>
As a convenience, <span class="application">gdk-pixbuf</span> also provides the
<code class="function">gdk_pixbuf_render_pixmap_and_mask()</code>
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.
</p>
</div>
<div class="sect2" title="Scaling Images">
<div class="titlepage"><div><div><h3 class="title">
<a name="id521103"></a>Scaling Images</h3></div></div></div>
<p>
<span class="application">Imlib</span> lets you render scaled image data at the time you
call <code class="function">gdk_imlib_render()</code>. Again, this
unfortunately scales and renders the whole image onto a new
pixmap.
</p>
<p>
<span class="application">gdk-pixbuf</span> 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.
<sup>[<a name="id523191" href="#ftn.id523191" class="footnote">1</a>]</sup>
</p>
<p>
Very simple applications may find it sufficient to use
<code class="function">gdk_pixbuf_scale_simple()</code> or
<code class="function">gdk_pixbuf_composite_color_simple()</code>.
These functions scale the whole source image at a time and
create a new pixbuf with the result.
</p>
<p>
More sophisticated applications will need to use
<code class="function">gdk_pixbuf_scale()</code>,
<code class="function">gdk_pixbuf_composite()</code>, or
<code class="function">gdk_pixbuf_composite_color()</code> instead.
These functions let you scale and composite an arbitrary
region of the source pixbuf onto a destination pixbuf that
you provide.
</p>
</div>
<div class="sect2" title="Getting Image Data from a Drawable">
<div class="titlepage"><div><div><h3 class="title">
<a name="id523249"></a>Getting Image Data from a Drawable</h3></div></div></div>
<p>
<span class="application">Imlib</span> 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
<code class="function">gdk_imlib_create_image_from_drawable()</code>
function.
</p>
<p>
<span class="application">gdk-pixbuf</span> provides the
<code class="function">gdk_pixbuf_get_from_drawable()</code> function
instead. It lets you specify a destination pixbuf instead
of always creating a new one for you.
</p>
</div>
<div class="footnotes">
<br><hr width="100" align="left">
<div class="footnote">
<p><sup>[<a name="ftn.id523191" href="#id523191" class="para">1</a>] </sup>
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.
</p>
<p>
Compositing against a single solid color is actually a
special case of a checkerboard; it simply uses checks of
the same color.
</p>
</div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.14</div>
</body>
</html>
|
