|
Server : Apache/2.2.17 (Unix) mod_ssl/2.2.17 OpenSSL/0.9.8e-fips-rhel5 DAV/2 PHP/5.2.17 System : Linux localhost 2.6.18-419.el5 #1 SMP Fri Feb 24 22:47:42 UTC 2017 x86_64 User : nobody ( 99) PHP Version : 5.2.17 Disable Function : NONE Directory : /usr/share/gtk-doc/html/gdk-pixbuf/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Converting Applications to gdk-pixbuf</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="index.html" title="The gdk-pixbuf Library">
<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.6 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="reference" href="rn01.html" title="API Reference">
<link rel="reference" href="rn02.html" title="Tools Reference">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
<link rel="appendix" href="apa.html" title="Appendix A. Porting applications from Imlib to gdk-pixbuf">
<link rel="appendix" href="license.html" title="Appendix B. License">
</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">The <span class="application">gdk-pixbuf</span> Library</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" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id3151291"></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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id3151324"></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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id3151432"></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_pixbuf_render_to_drawable()</code> or
<code class="function">gdk_pixbuf_render_to_drawable_alpha()</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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id3151514"></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="id3151550" href="#ftn.id3151550">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" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id3151617"></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.id3151550" href="#id3151550">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>
</body>
</html>