<refentry id="gdk-pixbuf-util">
<refmeta>
<refentrytitle>Utilities</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Utilities</refname><refpurpose>Utility and miscellaneous convenience functions.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gdk-pixbuf/gdk-pixbuf.h&gt;


<link linkend="GdkPixbuf">GdkPixbuf</link>*  <link linkend="gdk-pixbuf-add-alpha">gdk_pixbuf_add_alpha</link>            (const <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
                                             <link linkend="gboolean">gboolean</link> substitute_color,
                                             <link linkend="guchar">guchar</link> r,
                                             <link linkend="guchar">guchar</link> g,
                                             <link linkend="guchar">guchar</link> b);
void        <link linkend="gdk-pixbuf-copy-area">gdk_pixbuf_copy_area</link>            (const <link linkend="GdkPixbuf">GdkPixbuf</link> *src_pixbuf,
                                             int src_x,
                                             int src_y,
                                             int width,
                                             int height,
                                             <link linkend="GdkPixbuf">GdkPixbuf</link> *dest_pixbuf,
                                             int dest_x,
                                             int dest_y);
void        <link linkend="gdk-pixbuf-saturate-and-pixelate">gdk_pixbuf_saturate_and_pixelate</link>
                                            (const <link linkend="GdkPixbuf">GdkPixbuf</link> *src,
                                             <link linkend="GdkPixbuf">GdkPixbuf</link> *dest,
                                             <link linkend="gfloat">gfloat</link> saturation,
                                             <link linkend="gboolean">gboolean</link> pixelate);
void        <link linkend="gdk-pixbuf-fill">gdk_pixbuf_fill</link>                 (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
                                             <link linkend="guint32">guint32</link> pixel);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
  <para>
    These functions provide miscellaneous utilities for manipulating
    pixbufs.  The pixel data in pixbufs may of course be manipulated
    directly by applications, but several common operations can be
    performed by these functions instead.
  </para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="gdk-pixbuf-add-alpha">gdk_pixbuf_add_alpha ()</title>
<programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>*  gdk_pixbuf_add_alpha            (const <link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
                                             <link linkend="gboolean">gboolean</link> substitute_color,
                                             <link linkend="guchar">guchar</link> r,
                                             <link linkend="guchar">guchar</link> g,
                                             <link linkend="guchar">guchar</link> b);</programlisting>
<para>
Takes an existing pixbuf and adds an alpha channel to it.
If the existing pixbuf already had an alpha channel, the channel
values are copied from the original; otherwise, the alpha channel
is initialized to 255 (full opacity).
</para>
<para>
If <parameter>substitute_color</parameter> is <literal>TRUE</literal>, then the color specified by (<parameter>r</parameter>, <parameter>g</parameter>, <parameter>b</parameter>) will be
assigned zero opacity. That is, if you pass (255, 255, 255) for the
substitute color, all white pixels will become fully transparent.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pixbuf</parameter>&nbsp;:</entry>
<entry> A <link linkend="GdkPixbuf">GdkPixbuf</link>.
</entry></row>
<row><entry align="right"><parameter>substitute_color</parameter>&nbsp;:</entry>
<entry> Whether to set a color to zero opacity.  If this
is <literal>FALSE</literal>, then the (<parameter>r</parameter>, <parameter>g</parameter>, <parameter>b</parameter>) arguments will be ignored.
</entry></row>
<row><entry align="right"><parameter>r</parameter>&nbsp;:</entry>
<entry> Red value to substitute.
</entry></row>
<row><entry align="right"><parameter>g</parameter>&nbsp;:</entry>
<entry> Green value to substitute.
</entry></row>
<row><entry align="right"><parameter>b</parameter>&nbsp;:</entry>
<entry> Blue value to substitute.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A newly-created pixbuf with a reference count of 1.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-copy-area">gdk_pixbuf_copy_area ()</title>
<programlisting>void        gdk_pixbuf_copy_area            (const <link linkend="GdkPixbuf">GdkPixbuf</link> *src_pixbuf,
                                             int src_x,
                                             int src_y,
                                             int width,
                                             int height,
                                             <link linkend="GdkPixbuf">GdkPixbuf</link> *dest_pixbuf,
                                             int dest_x,
                                             int dest_y);</programlisting>
<para>
Copies a rectangular area from <parameter>src_pixbuf</parameter> to <parameter>dest_pixbuf</parameter>.  Conversion of
pixbuf formats is done automatically.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>src_pixbuf</parameter>&nbsp;:</entry>
<entry> Source pixbuf.
</entry></row>
<row><entry align="right"><parameter>src_x</parameter>&nbsp;:</entry>
<entry> Source X coordinate within <parameter>src_pixbuf</parameter>.
</entry></row>
<row><entry align="right"><parameter>src_y</parameter>&nbsp;:</entry>
<entry> Source Y coordinate within <parameter>src_pixbuf</parameter>.
</entry></row>
<row><entry align="right"><parameter>width</parameter>&nbsp;:</entry>
<entry> Width of the area to copy.
</entry></row>
<row><entry align="right"><parameter>height</parameter>&nbsp;:</entry>
<entry> Height of the area to copy.
</entry></row>
<row><entry align="right"><parameter>dest_pixbuf</parameter>&nbsp;:</entry>
<entry> Destination pixbuf.
</entry></row>
<row><entry align="right"><parameter>dest_x</parameter>&nbsp;:</entry>
<entry> X coordinate within <parameter>dest_pixbuf</parameter>.
</entry></row>
<row><entry align="right"><parameter>dest_y</parameter>&nbsp;:</entry>
<entry> Y coordinate within <parameter>dest_pixbuf</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-saturate-and-pixelate">gdk_pixbuf_saturate_and_pixelate ()</title>
<programlisting>void        gdk_pixbuf_saturate_and_pixelate
                                            (const <link linkend="GdkPixbuf">GdkPixbuf</link> *src,
                                             <link linkend="GdkPixbuf">GdkPixbuf</link> *dest,
                                             <link linkend="gfloat">gfloat</link> saturation,
                                             <link linkend="gboolean">gboolean</link> pixelate);</programlisting>
<para>
Modifies saturation and optionally pixelates <parameter>src</parameter>, placing the
result in <parameter>dest</parameter>. <parameter>src</parameter> and <parameter>dest</parameter> may be the same pixbuf with no ill
effects.  If <parameter>saturation</parameter> is 1.0 then saturation is not changed. If
it's less than 1.0, saturation is reduced (the image is darkened);
if greater than 1.0, saturation is increased (the image is
brightened). If <parameter>pixelate</parameter> is <literal>TRUE</literal>, then pixels are faded in a
checkerboard pattern to create a pixelated image. <parameter>src</parameter> and <parameter>dest</parameter>
must have the same image format, size, and rowstride.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>src</parameter>&nbsp;:</entry>
<entry> source image
</entry></row>
<row><entry align="right"><parameter>dest</parameter>&nbsp;:</entry>
<entry> place to write modified version of <parameter>src</parameter>
</entry></row>
<row><entry align="right"><parameter>saturation</parameter>&nbsp;:</entry>
<entry> saturation factor
</entry></row>
<row><entry align="right"><parameter>pixelate</parameter>&nbsp;:</entry>
<entry> whether to pixelate
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gdk-pixbuf-fill">gdk_pixbuf_fill ()</title>
<programlisting>void        gdk_pixbuf_fill                 (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf,
                                             <link linkend="guint32">guint32</link> pixel);</programlisting>
<para>
Clears a pixbuf to the given RGBA value, converting the RGBA value into
the pixbuf's pixel format. The alpha will be ignored if the pixbuf
doesn't have an alpha channel.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pixbuf</parameter>&nbsp;:</entry>
<entry> a <link linkend="GdkPixbuf">GdkPixbuf</link>
</entry></row>
<row><entry align="right"><parameter>pixel</parameter>&nbsp;:</entry>
<entry> RGBA pixel to clear to
        (0xffffffff is opaque white, 0x00000000 transparent black)
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
  <para>
    <link linkend="GdkPixbuf">GdkPixbuf</link>
  </para>
</refsect1>

</refentry>
